REST API kullanarak önerileri entegre etme

Google TV Video Discovery REST API, iş ortaklarının arka uç sunucularından Google TV ve Android TV cihazlarına kişiselleştirilmemiş öneri adayları göndermesine olanak tanır. Adayları arka uçlarından göndermek, iş ortağının kataloğunu ve canlı programlama önerilerini bu cihazlarda güncel tutar ve kullanıcıların iş ortağının uygulamasını açmasını gerektirmez.

İş ortakları, adayları öneri feed'lerine gönderir. Google, iş ortağı için her feed'i oluşturur ve feed'in gösterileceği ülkeleri veya bölgeleri ve TV cihazı dillerini yapılandırır. Feed'de filmler, TV programları ve canlı TV programları yer alabilir.

Kullanıcının cihazından kişiselleştirilmiş öneriler yayınlamak istiyorsanız Engage SDK'yı kullanarak cihaz üzerinde önerileri entegre etme başlıklı makaleyi inceleyin.

Ön koşullar

REST API ile entegrasyon yapmadan önce aşağıdakilere sahip olduğunuzdan emin olun:

  • API istekleri göndermek için bir Google Cloud projesi.
  • Kuruluşunuzla ilişkili bir Google Workspace hesabı.
  • İlk katılım sırasında Google TV iş ortağı temsilciniz tarafından sağlanan iş ortağı kimliğiniz ve öneri feed'i kimlikleriniz. Bu kimliklerin nasıl kullanıldığını öğrenmek için Öneri feed'leri bölümüne bakın.

Erişim kazanın

Google TV Video Discovery REST API'ye erişim, kayıtlı Google TV medya iş ortaklarıyla sınırlıdır. Her arayanın kimliği, sunucuda tam olarak bir iş ortağı kimliğiyle eşlenen bir Google Cloud hizmet hesabı kullanılarak doğrulanır.

API erişimi isteyip yapılandırmak için aşağıdaki adımları uygulayın:

  1. Google Workspace hesabı oluşturun. Kuruluşunuz için hesap oluşturmak üzere Google Workspace Destek Ekibi sayfasındaki talimatları uygulayın.
  2. Google Workspace müşteri kimliğinizi bulma Müşteri kimliğinizi bulma başlıklı makaledeki adımları uygulayarak müşteri kimliğinizi (ör. C0123abcd) bulun.
  3. Google Cloud projesi ve hizmet hesabı oluşturun. Google Workspace kuruluşunuzun altındaki Google Cloud Console'da, arka uç sunucunuz için bir Google Cloud projesi ve hizmet hesabı oluşturun.
  4. İş ortağı oryantasyonu isteyin. Google Workspace müşteri kimliğinizi, Google Cloud proje kimliğinizi ve hizmet hesabı e-posta adresinizi (veya benzersiz sayısal kimliğinizi), adayları göndermek istediğiniz ülkeler veya bölgeler ve TV cihazı dilleriyle birlikte Google TV iş ortağı temsilcinize iletin. Google TV iş ortağı temsilciniz, Google Workspace kuruluşunuzu, projenizi ve hizmet hesabınızı iş ortağı kimliğinizle eşledikten sonra sizi bilgilendirir ve iş ortağınız için oluşturulan öneri feed'i kimliklerini size verir.
  5. API'yi etkinleştirme ve kimlik bilgileri oluşturma Temsilciniz erişim izni verildiğini onayladıktan sonra Google Cloud projenizde Google TV Video Discovery API'yi (tvvideodiscovery.googleapis.com) etkinleştirin ve hizmet hesabınız için OAuth 2.0 kimlik bilgileri oluşturun.
  6. İsteklerinizin kimliğini doğrulayın. Aşağıdaki OAuth kapsamını kullanarak OAuth 2.0 erişim jetonları isteyin ve her çağrıda jetonu Authorization: Bearer HTTP üstbilgisinde iletin:

    https://www.googleapis.com/auth/tvvideodiscovery
    

Hız sınırları

replaceCandidates istekleri, proje başına aşağıdaki sıklık sınırlarına ve istek başına yük sınırlarına tabidir:

Sınır Değer
Google Cloud projesi başına bir dakika içinde gönderilen istek sayısı 5
Google Cloud projesi başına günlük istek sayısı 100
İstek başına RecommendationCandidate öğe 1-25

Hazırlık feed'ine yapılan istekler, ilgili üretim feed'ine yapılan isteklerle aynı kotaya dahil edilir.

Öneri feed'leri

API, öneri adaylarını öneri feed'leri halinde düzenler. Feed'ler, şu biçimdeki bir kaynak adıyla tanımlanır:

partners/{partner}/recommendationsFeeds/{recommendationsFeed}

İş Ortakları

{partner}, ilk katılım sırasında Google'ın size atadığı iş ortağı kimliğidir. Kimlik doğrulaması için kullandığınız hizmet hesabı tam olarak bir iş ortağı kimliğiyle eşlenir. Başka bir iş ortağının adını içeren istekler 403 PERMISSION_DENIED hatasıyla başarısız olur.

Feed kimlikleri

{recommendationsFeed}, ilk katılım sırasında Google'ın sizin için oluşturduğu bir feed kimliğidir. API ile feed oluşturamazsınız.

Her feed, Google'ın feed'i oluştururken yapılandırdığı bir kitleyi hedefler:

  • Ülkeler veya bölgeler: Feed'deki adayların gösterildiği yerler.
  • TV cihaz dilleri: Hedeflenen kullanıcıların TV cihazlarında ayarladığı diller. Bu, gönderdiğiniz metnin dili değildir. Birden fazla dilde metin sağlamak için LocalizedString bölümüne bakın.

Google, feed'deki adayların Google TV ve Android TV cihazlarında nerede görüneceğine karar verir. Adayları her feed'e aynı şekilde gönderirsiniz.

Hazırlık feed'leri

Her feed'in {recommendationsFeed}-staging adlı eşleşen bir hazırlık feed'i vardır. Hazırlık feed'i yalnızca izin verilenler listesindeki test hesaplarına sunulur. Adayları üretim feed'ine göndermeden önce entegrasyonunuzu doğrulamak için bu feed'i kullanın.

Hazırlık feed'leri, üretim feed'leriyle aynı uç noktayı, kimlik bilgilerini, istek doğrulamasını ve kotayı kullanır. Yalnızca kitle farklıdır.

Değiştirme

Feed, değiştirme birimidir. Her replaceCandidates çağrısı, ilgili feed için daha önce depolanan tüm adayların yerini alır ve diğer feed'leri etkilemez.

Öneri adaylarını değiştirme

Bir feed için öneri adaylarının tam listesini göndermek üzere partners.recommendationsFeeds.replaceCandidates yöntemini kullanın.

HTTP isteği

POST https://tvvideodiscovery.googleapis.com/v1/{name=partners/*/recommendationsFeeds/*}:replaceCandidates

URL yolu, adayları değiştirilen feed'in kaynak adını içerir. İstek içeriği, URL yolunun parçası olmayan her alanı içerir.

Yol parametreleri

Parametre Açıklama
name Zorunlu. Feed'in partners/{partner}/recommendationsFeeds/{recommendationsFeed} biçimindeki kaynak adı. {partner}, hizmet hesabınızın eşlendiği iş ortağı kimliği olmalıdır. {recommendationsFeed}, Google'ın ilgili iş ortağı için oluşturduğu bir feed kimliği veya -staging son ekine sahip feed kimliği olmalıdır.

ReplaceCandidatesRequest

JSON istek içeriği aşağıdaki yapıya sahiptir:

Alan Tür Zorunlu Açıklama
recommendation_candidates array of RecommendationCandidate Evet 1 ila 25 RecommendationCandidate öğe içeren bir liste. Bu adaylar, feed'in mevcut adaylarının yerini alır.

Aday şemaları

recommendation_candidates içindeki her öğe, bir aday türü yük, isteğe bağlı öneri nedenleri ve isteğe bağlı kullanım dönemleri içeren bir RecommendationCandidate nesnesidir.

RecommendationCandidate

RecommendationCandidate nesnesi tam olarak bir medya türü yük alanı, isteğe bağlı öneri nedenleri ve isteğe bağlı kullanılabilirlik aralıkları içerir.

candidate_type birleşik alanı

candidate_type gerekli: Aşağıdaki alanlardan tam olarak birini ayarlayın. Alanlar birbirini dışlar ve hiçbiri veya birden fazlası ayarlanmayan adaylar reddedilir. JSON'da candidate_type anahtarı yok. Seçilen alanı doğrudan RecommendationCandidate nesnesinde ayarlayın.

Alan Tür Açıklama
movie_candidate MovieCandidate Seç-izle film (MovieCandidate bölümüne bakın).
tv_show_candidate TvShowCandidate Program düzeyinde bir TV programı (bkz. TvShowCandidate).
live_tv_program_candidate LiveTvProgramCandidate Planlanmış bir canlı TV yayını veya canlı yayınlanan etkinlik (bkz. LiveTvProgramCandidate).

Bağlam ve kullanılabilirlik

Her iki alan da isteğe bağlıdır:

Alan Tür Zorunlu Açıklama
recommendation_contexts array of RecommendationContext Hayır Adayın neden önerildiği ve her bir nedenin ne kadar süre geçerli olduğu (bkz. RecommendationContext).
availability_intervals array of Interval Hayır Adayın gösterilebileceği zaman aralıkları (Interval bölümüne bakın). Her aralık, start_time (dahil) ile başlar ve end_time (hariç) ile biter. Ayarlanmazsa aday, depolandığı sürece uygun olur. Tüm aralıkları geçmişte olan bir aday hiçbir zaman gösterilmez.

MovieCandidate

MovieCandidate nesnesi, seç-izle filmi temsil eder:

Alan Tür Zorunlu Açıklama
title LocalizedString Evet Filmin başlığı (LocalizedString bölümüne bakın). Her değer 1 ila 100 Unicode kod noktasıdır ve gönderildiği şekilde gösterilir.
description LocalizedString Evet Filmin kısa açıklaması (LocalizedString bölümüne bakın). Her değer 1 ila 400 Unicode kod noktasıdır.
localized_media_images array of LocalizedMediaImage Evet 16:9 albüm kapağı resimleri, dil başına bir giriş (bkz. LocalizedMediaImage). En az bir resim içermelidir. Mümkün olan en büyük kaynağı sağlayın. 1920x1080 piksel önerilir.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Evet Platform ve dil başına derin bağlantılar (LocalizedProviderPlaybackUri bölümüne bakın). En az bir girişte PLATFORM_ANDROID_TV listelenmelidir.
release_date Date Evet Filmin yayın tarihi (Date bölümüne bakın).
external_entity_ids array of ExternalEntityId Hayır Varlık eşleştirme için harici katalog tanımlayıcıları (bkz. ExternalEntityId). Tanımlayıcı türü başına en fazla bir giriş.
duration string (Duration) Hayır Filmin süresi (Duration bölümüne bakın). Örneğin, 2 saat için "7200s".
content_ratings array of ContentRating Hayır Resmi içerik derecelendirmeleri (ContentRating bölümüne bakın).

TvShowCandidate

TvShowCandidate nesnesi, TV programını program düzeyinde temsil eder. Google TV ve Android TV cihazlarda program için bir kart gösterilir. Oynatmanın program sayfasında mı yoksa belirli bir bölümde mi başlayacağına karar vermek için derin bağlantıyı kullanın.

Alan Tür Zorunlu Açıklama
title LocalizedString Evet TV programının başlığı (LocalizedString bölümüne bakın). Her değer 1 ila 100 Unicode kod noktasıdır ve gönderildiği şekilde gösterilir.
description LocalizedString Evet TV dizisinin kısa açıklaması (LocalizedString bölümüne bakın). Her değer 1 ila 400 Unicode kod noktasıdır.
localized_media_images array of LocalizedMediaImage Evet 16:9 albüm kapağı resimleri, dil başına bir giriş (bkz. LocalizedMediaImage). En az bir resim içermelidir. Mümkün olan en büyük kaynağı sağlayın. 1920x1080 piksel önerilir.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Evet Platform ve dil başına derin bağlantılar (LocalizedProviderPlaybackUri bölümüne bakın). En az bir girişte PLATFORM_ANDROID_TV listelenmelidir. uri, program sayfasına veya bir bölüme yönlendirebilir.
first_episode_air_date Date Evet İlk bölümün yayın tarihi (Date bölümüne bakın).
external_entity_ids array of ExternalEntityId Hayır Varlık eşleştirme için harici katalog tanımlayıcıları (bkz. ExternalEntityId). Tanımlayıcı türü başına en fazla bir giriş.
season_count integer (int32) Hayır Hizmetinizde bulunan sezon sayısı.
content_ratings array of ContentRating Hayır Resmi içerik derecelendirmeleri (ContentRating bölümüne bakın).

LiveTvProgramCandidate

LiveTvProgramCandidate nesnesi, planlanmış bir canlı TV yayınını veya canlı yayınlanan etkinliği temsil eder. Yayın penceresi, adayın bir parçasıdır ve üst adayın availability_intervals değerinden ayrıdır. Bu değer, kartın ne zaman gösterilebileceğini kontrol eder.

Alan Tür Zorunlu Açıklama
title LocalizedString Evet Canlı TV programının başlığı (LocalizedString bölümüne bakın). Her değer 1 ila 100 Unicode kod noktasıdır ve gönderildiği şekilde gösterilir.
description LocalizedString Evet Canlı TV programının kısa açıklaması (LocalizedString bölümüne bakın). Her değer 1 ila 400 Unicode kod noktasıdır.
localized_media_images array of LocalizedMediaImage Evet 16:9 albüm kapağı resimleri, dil başına bir giriş (bkz. LocalizedMediaImage). En az bir resim içermelidir. Mümkün olan en büyük kaynağı sağlayın. 1920x1080 piksel önerilir.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Evet Platform ve dil başına derin bağlantılar (LocalizedProviderPlaybackUri bölümüne bakın). En az bir girişte PLATFORM_ANDROID_TV listelenmelidir.
broadcast_interval Interval Evet Programın yayın başlangıç ve bitiş zamanı (Interval bölümüne bakın). Hem start_time hem de end_time gereklidir.
external_entity_ids array of ExternalEntityId Hayır Varlık eşleştirme için harici katalog tanımlayıcıları (bkz. ExternalEntityId). Tanımlayıcı türü başına en fazla bir giriş.
content_ratings array of ContentRating Hayır Resmi içerik derecelendirmeleri (ContentRating bölümüne bakın).

Destekleyici şemalar

Aday yükler; yerelleştirilmiş metin, derin bağlantılar, posterler, harici tanımlayıcılar, öneri nedenleri, görüntüleme aralıkları, içerik derecelendirmeleri ve bilinen tarih ve saat türleri için aşağıdaki paylaşılan nesnelere referans verir.

LocalizedString

LocalizedString nesnesi, bir veya daha fazla dilde aynı metni taşır. Google TV ve Android TV cihazlarının, kullanıcının TV cihazının diliyle eşleşen metni gösterebilmesi için her değer kendi diliyle etiketlenir:

Alan Tür Zorunlu Açıklama
values array of LocalizedText Evet Sağladığınız her dildeki metin (bkz. LocalizedText). En az bir değer içermelidir.

LocalizedText

LocalizedText nesnesi tek bir dildeki metindir:

Alan Tür Zorunlu Açıklama
text string Evet language_code tarafından belirtilen dildeki metin.
language_code string Evet text için BCP-47 dil kodu (ör. "en-US" veya "sr-Latn").

LocalizedMediaImage

LocalizedMediaImage nesnesi, bir resmi, resimdeki metnin diliyle eşleştirir:

Alan Tür Zorunlu Açıklama
language_code string Evet Resimdeki metnin BCP-47 dil kodu (ör. "en-US" veya "sr-Latn").
image MediaImage Evet 16:9 oranında bir resim (MediaImage bölümüne bakın). Mevcut en büyük kaynağı sağlayın; 1920x1080 piksel önerilir.

LocalizedProviderPlaybackUri

LocalizedProviderPlaybackUri nesnesi, bir derin bağlantıyı açtığı içeriğin dili ve onu açan uygulamayla eşleştirir:

Alan Tür Zorunlu Açıklama
playback_uri PlaybackUri Evet Derin bağlantı ve geçerli olduğu platformlar (PlaybackUri bölümüne bakın).
language_code string Evet Derin bağlantının açtığı içeriğin BCP-47 dil kodu (ör. "en-US" veya "sr-Latn").
package_name string Evet Derin bağlantıyı açmak için kullanılan Android uygulama paketi adı (ör. "com.example.tvapp").

PlaybackUri

PlaybackUri nesnesi, bir derin bağlantıyı ve hedef platformlarını tanımlar:

Alan Tür Zorunlu Açıklama
uri string Evet Uygulamanızda adayın oynatılmasını başlatan derin bağlantı URI'si.
platforms array of string (enum) Evet Bu derin bağlantının geçerli olduğu platformlar. İzin verilen değerler: PLATFORM_UNSPECIFIED, PLATFORM_ANDROID_TV, PLATFORM_ANDROID, PLATFORM_IOS. Google TV ve Android TV cihazları için PLATFORM_ANDROID_TV ekleyin.

MediaImage

MediaImage nesnesi bir resim URL'sini, piksel boyutlarını ve erişilebilirlik metnini belirtir:

Alan Tür Zorunlu Açıklama
url string Evet Resmin herkesin erişimine açık HTTPS URL'si.
width integer Evet Piksel cinsinden değiştirilmemiş (maksimum) resim genişliği.
height integer Evet Piksel cinsinden değiştirilmemiş (maksimum) resim yüksekliği.
accessibility_text string Evet Resmi açıklayan erişilebilirlik (alternatif) metni.

ExternalEntityId

ExternalEntityId nesnesi, bir adayı harici bir katalogdaki tanımlayıcıyla eşler. Giriş başına aşağıdaki alanlardan tam olarak birini ayarlayın ve bir adayın external_entity_ids listesine tanımlayıcı türü başına en fazla bir giriş ekleyin:

Alan Tür Zorunlu Açıklama
tms_root_id string Şunlardan biri: Gracenote TMS kök kimliği. Bir başlığı (film, program veya bölüm) tanımlar.
tms_id string Şunlardan biri: Gracenote TMS varyant kimliği. Bir sürümü veya yayın listesini tanımlar.
data_feed_element_id string Şunlardan biri: Medya İşlemleri veri feed'inizdeki varlık kimliği. Bu değer, kaynak adının {recommendationsFeed} segmentiyle ilişkili değildir.

RecommendationContext

RecommendationContext nesnesi, bir adayın neden önerildiğini ve bu açıklamanın ne kadar süre geçerli olduğunu açıklar:

Alan Tür Zorunlu Açıklama
recommendation_reason RecommendationReason Hayır Adayın neden önerildiği (RecommendationReason bölümüne bakın).
validity_interval Interval Hayır Bu bağlamın geçerli olduğu zaman aralığı (bkz. Interval). Örneğin, bir aday yalnızca sınırlı sayıda gün boyunca yenidir. Ayarlanmazsa bağlam, aday saklandığı sürece geçerli olur.

RecommendationReason

RecommendationReason nesnesi bir neden içerir. Aşağıdaki alanlardan tam olarak birini ayarlayın:

Alan Tür Zorunlu Açıklama
top_on_partner object Şunlardan biri: Aday, hizmetinizdeki en iyi öğelerden biridir. Tek bir pozitif tam sayı alanı rank içerir (örneğin, "İş Ortağında İlk 1" için {"rank": 1}).
popular_on_partner object Şunlardan biri: Aday, hizmetinizde popülerdir. Boş bir nesne ({}) iletin.
new_on_partner object Şunlardan biri: Aday, hizmetinizde yenidir. Boş bir nesne ({}) iletin.
generic object Şunlardan biri: Özel bir neden. Tek bir LocalizedString alanı generic_reason içerir (LocalizedString bölümüne bakın). Her değer 1 ila 100 Unicode kod noktasıdır.

ContentRating

ContentRating nesnesi, bir derecelendirme kuruluşu tarafından atanan resmi içerik derecelendirmesini temsil eder:

Alan Tür Zorunlu Açıklama
rating_system string Evet Derecelendirme kuruluşu veya sistemi (ör. "MPAA", "BBFC" veya "CBFC").
rating_value string Evet rating_system tarafından tanımlanan derecelendirme (ör. "PG-13" veya "U/A 13+").

Timestamp

Timestamp, JSON'da UTC'de Z son ekiyle RFC 3339 dizesi olarak kodlanır (ör. "2026-10-01T18:00:00Z"). Kesirli saniyelere izin verilir (ör. "2026-10-01T18:00:00.500Z").

Duration

Duration, JSON'da saniye sayısını ve ardından s son ekini içeren bir dize olarak kodlanır. Örneğin, 2 saat için "7200s" kullanılır. Kesirli saniyelere izin verilir (ör. "5400.5s").

Date

Date, saat dilimi olmayan bir takvim tarihidir. JSON'da aşağıdaki alanları içeren bir nesne olarak kodlanır:

Alan Tür Zorunlu Açıklama
year integer Evet Tarihin yılı (ör. 2025).
month integer Hayır Yılın ayı (1 ile 12 arasında). 0 değerine ayarlayın veya ay bilinmiyorsa boş bırakın.
day integer Hayır Ayın günü (1 ile 31 arasında ve belirtilen yıl ve ay için geçerli). 0 değerine ayarlayın veya gün bilinmiyorsa atlayın. month gerektirir.

Örneğin, {"year": 2025, "month": 1, "day": 17} 17 Ocak 2025'i, {"year": 2025, "month": 1} günü bilinmeyen Ocak 2025'i, {"year": 2025} ise ayı ve günü bilinmeyen 2025'teki bir tarihi temsil eder.

Interval

Interval, start_time (dahil) ile başlayıp end_time (hariç) ile biten yarı açık bir zaman aralığıdır. T zamanı, start_time <= T ve T < end_time aralığındadır.

Alan Tür Zorunlu Açıklama
start_time string (Timestamp) Evet Pencerenin başlangıç zamanı dahildir (Timestamp bölümüne bakın), örneğin "2026-10-01T18:00:00Z".
end_time string (Timestamp) Evet Pencerenin bitiş zamanı dahil değildir (Timestamp bölümüne bakın), örneğin "2026-10-01T21:00:00Z". start_time tarihinden sonra olmalıdır.

Örnek istek

Aşağıdaki örnekte, example-partner iş ortağının in-en-cricket feed'indeki adaylar üç adayla (bir film, bir TV dizisi ve bir canlı TV programı) değiştirilmektedir. Filmde iki dilde metin var:

curl -X POST \
  "https://tvvideodiscovery.googleapis.com/v1/partners/example-partner/recommendationsFeeds/in-en-cricket:replaceCandidates" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "recommendation_candidates": [
      {
        "movie_candidate": {
          "title": {
            "values": [
              {
                "text": "Example Action Movie",
                "language_code": "en-US"
              },
              {
                "text": "Película de acción de ejemplo",
                "language_code": "es-419"
              }
            ]
          },
          "description": {
            "values": [
              {
                "text": "An example action movie synopsis.",
                "language_code": "en-US"
              },
              {
                "text": "Sinopsis de una película de acción de ejemplo.",
                "language_code": "es-419"
              }
            ]
          },
          "localized_media_images": [
            {
              "language_code": "en-US",
              "image": {
                "url": "https://www.example.com/images/movie-1001-16x9-en.jpg",
                "width": 1920,
                "height": 1080,
                "accessibility_text": "Artwork for Example Action Movie"
              }
            },
            {
              "language_code": "es-419",
              "image": {
                "url": "https://www.example.com/images/movie-1001-16x9-es.jpg",
                "width": 1920,
                "height": 1080,
                "accessibility_text": "Imagen de Película de acción de ejemplo"
              }
            }
          ],
          "localized_provider_playback_uris": [
            {
              "playback_uri": {
                "uri": "https://www.example.com/watch/movie-1001?lang=en",
                "platforms": ["PLATFORM_ANDROID_TV", "PLATFORM_ANDROID"]
              },
              "language_code": "en-US",
              "package_name": "com.example.tvapp"
            },
            {
              "playback_uri": {
                "uri": "https://www.example.com/watch/movie-1001?lang=es",
                "platforms": ["PLATFORM_ANDROID_TV", "PLATFORM_ANDROID"]
              },
              "language_code": "es-419",
              "package_name": "com.example.tvapp"
            }
          ],
          "release_date": {
            "year": 2025,
            "month": 11,
            "day": 14
          },
          "external_entity_ids": [
            {
              "tms_root_id": "MV001234560000"
            }
          ],
          "duration": "7200s",
          "content_ratings": [
            {
              "rating_system": "MPAA",
              "rating_value": "PG-13"
            }
          ]
        },
        "recommendation_contexts": [
          {
            "recommendation_reason": {
              "top_on_partner": {
                "rank": 1
              }
            }
          }
        ],
        "availability_intervals": [
          {
            "start_time": "2026-11-01T00:00:00Z",
            "end_time": "2026-12-01T00:00:00Z"
          }
        ]
      },
      {
        "tv_show_candidate": {
          "title": {
            "values": [
              {
                "text": "Example Drama Series",
                "language_code": "en-US"
              }
            ]
          },
          "description": {
            "values": [
              {
                "text": "An example drama series synopsis.",
                "language_code": "en-US"
              }
            ]
          },
          "localized_media_images": [
            {
              "language_code": "en-US",
              "image": {
                "url": "https://www.example.com/images/show-2002-16x9.jpg",
                "width": 1920,
                "height": 1080,
                "accessibility_text": "Artwork for Example Drama Series"
              }
            }
          ],
          "localized_provider_playback_uris": [
            {
              "playback_uri": {
                "uri": "https://www.example.com/watch/show-2002",
                "platforms": ["PLATFORM_ANDROID_TV"]
              },
              "language_code": "en-US",
              "package_name": "com.example.tvapp"
            }
          ],
          "first_episode_air_date": {
            "year": 2024,
            "month": 3,
            "day": 8
          },
          "external_entity_ids": [
            {
              "data_feed_element_id": "show-2002"
            }
          ],
          "season_count": 3,
          "content_ratings": [
            {
              "rating_system": "TV_PG",
              "rating_value": "TV-14"
            }
          ]
        },
        "recommendation_contexts": [
          {
            "recommendation_reason": {
              "new_on_partner": {}
            },
            "validity_interval": {
              "start_time": "2026-11-01T00:00:00Z",
              "end_time": "2026-11-15T00:00:00Z"
            }
          }
        ],
        "availability_intervals": [
          {
            "start_time": "2026-11-01T00:00:00Z",
            "end_time": "2026-12-01T00:00:00Z"
          }
        ]
      },
      {
        "live_tv_program_candidate": {
          "title": {
            "values": [
              {
                "text": "Championship Live Broadcast",
                "language_code": "en-US"
              }
            ]
          },
          "description": {
            "values": [
              {
                "text": "Live coverage of the championship match.",
                "language_code": "en-US"
              }
            ]
          },
          "localized_media_images": [
            {
              "language_code": "en-US",
              "image": {
                "url": "https://www.example.com/images/live-prog-500-16x9.jpg",
                "width": 1920,
                "height": 1080,
                "accessibility_text": "Artwork for Championship Live Broadcast"
              }
            }
          ],
          "localized_provider_playback_uris": [
            {
              "playback_uri": {
                "uri": "https://www.example.com/live/sports-1",
                "platforms": ["PLATFORM_ANDROID_TV"]
              },
              "language_code": "en-US",
              "package_name": "com.example.tvapp"
            }
          ],
          "broadcast_interval": {
            "start_time": "2026-11-15T18:00:00Z",
            "end_time": "2026-11-15T21:00:00Z"
          },
          "external_entity_ids": [
            {
              "tms_id": "EP012345670001"
            }
          ],
          "content_ratings": [
            {
              "rating_system": "TV_PG",
              "rating_value": "TV-PG"
            }
          ]
        },
        "recommendation_contexts": [
          {
            "recommendation_reason": {
              "generic": {
                "generic_reason": {
                  "values": [
                    {
                      "text": "Live this weekend",
                      "language_code": "en-US"
                    }
                  ]
                }
              }
            }
          }
        ],
        "availability_intervals": [
          {
            "start_time": "2026-11-14T18:00:00Z",
            "end_time": "2026-11-15T21:00:00Z"
          }
        ]
      }
    ]
  }'

Yanıt ve değiştirme davranışı

Bu bölümde, replaceCandidates tarafından döndürülen HTTP yanıtı ve her çağrının, depolanan adaylarınızı nasıl güncellediği açıklanmaktadır.

ReplaceCandidatesResponse

İstek başarılı olursa API, ReplaceCandidatesResponse gövdesiyle HTTP 200 OK döndürür:

Alan Tür Açıklama
replaced_candidates_count integer (int32) Değiştirilen aday sayısı.

Önceki örnek istek için yanıt şöyledir:

{
  "replaced_candidates_count": 3
}

Değiştirme davranışı

Entegrasyonunuzu tasarlamak için replaceCandidates'in kayıtlı adayları nasıl güncellediğini anlamanız gerekir:

  • Feed başına tam değiştirme. Her çağrı, URL yolunda adı verilen feed için önceden depolanan aday listesini tamamen değiştirir. Her zaman ilgili feed'deki etkin adayların tam grubunu gönderin.
  • Diğer feed'ler değişmez. Aday göndermediğiniz feed'ler, siz aday gönderene kadar değişmeden kalır. Örneğin, bir feed'in adaylarını değiştirmek, başka bir feed için depolanan adaylarınızı değiştirmez ve {recommendationsFeed}-staging feed'inin adaylarını değiştirmek, {recommendationsFeed} feed'ini değiştirmez.
  • Feed başına bir çağrı. Birden fazla feed'i güncellemek için her feed için bir çağrı yapın. Çağrılar birbirinden bağımsızdır: Biri başarısız olursa diğer feed'ler yeni adaylarını korur ve yalnızca başarısız olan çağrıyı yeniden denersiniz.
  • Etkin feed'leri en az 30 günde bir yeniden gönderin. Bir feed'e ait kataloğunuz değişmemiş olsa bile her etkin feed'i en az 30 günde bir (veya rastgele gecikmeyle düzenli günlük ya da haftalık bir programla) yeniden gönderin. Böylece adaylarınız etkin kalır ve süresi dolmaz. availability_intervals end_time değerini çok ileri bir tarihe ayarlamak, periyodik olarak yeniden gönderme işleminin yerini almaz.
  • Atomik yürütme. API, isteği atomik olarak uygular. Adaylardan herhangi biri doğrulamadan geçemezse API, isteğin tamamını reddeder ve feed, önceki adaylarını korur.