Integracja rekomendacji za pomocą interfejsu API typu REST

Interfejs REST API Google TV Video Discovery umożliwia partnerom wysyłanie niespersonalizowanych propozycji rekomendacji do urządzeń z Google TV i urządzeń z Androidem TV z serwerów backendu. Wysyłanie kandydatów z backendu pozwala na aktualizowanie katalogu partnera i rekomendacji programów na żywo na tych urządzeniach bez konieczności otwierania aplikacji partnera przez użytkowników.

Partnerzy wysyłają kandydatów do kanałów rekomendacji. Google tworzy każdy plik danych dla partnera i konfiguruje kraje lub regiony oraz języki urządzeń telewizyjnych, na których plik danych jest wyświetlany. Plik danych może zawierać filmy, seriale i programy telewizyjne oraz programy telewizyjne na żywo.

Jeśli chcesz publikować spersonalizowane rekomendacje z urządzenia użytkownika, zapoznaj się z artykułem Integracja rekomendacji na urządzeniu za pomocą pakietu Engage SDK.

Wymagania wstępne

Zanim przeprowadzisz integrację z interfejsem REST API, upewnij się, że masz:

  • projekt Google Cloud, z którego będą wysyłane żądania do interfejsu API;
  • Konto Google Workspace powiązane z Twoją organizacją.
  • Identyfikator partnera i identyfikatory kanału rekomendacji, które podczas wprowadzania podał przedstawiciel partnera Google TV. Informacje o tym, jak są używane te identyfikatory, znajdziesz w artykule o plikach danych z rekomendacjami.

Uzyskaj dostęp

Dostęp do interfejsu Google TV Video Discovery REST API jest ograniczony do zarejestrowanych partnerów Google TV zajmujących się mediami. Każdy element wywołujący jest uwierzytelniany za pomocą konta usługi Google Cloud, które jest mapowane na serwerze na dokładnie 1 identyfikator partnera.

Aby poprosić o dostęp do interfejsu API i go skonfigurować, wykonaj te czynności:

  1. Utwórz konto Google Workspace. Postępuj zgodnie z instrukcjami na stronie pomocy Google Workspace, aby skonfigurować konto dla swojej organizacji.
  2. Znajdź identyfikator klienta Google Workspace. Znajdź swój identyfikator klienta (np. C0123abcd), wykonując czynności opisane w artykule Znajdowanie identyfikatora klienta.
  3. Utwórz projekt w chmurze Google Cloud i konto usługi. W konsoli Google Cloud w organizacji Google Workspace utwórz projekt Google Cloud i konto usługi dla serwera backendu.
  4. Poproś o wprowadzenie partnera. Podaj przedstawicielowi partnera Google TV identyfikator klienta Google Workspace, identyfikator projektu w chmurze Google i adres e-mail konta usługi (lub unikalny identyfikator numeryczny) wraz z krajami lub regionami i językami urządzeń TV, do których chcesz wysyłać kandydatów. Przedstawiciel partnera Google TV powiadomi Cię po zmapowaniu organizacji Google Workspace, projektu i konta usługi na identyfikator partnera i poda identyfikatory kanałów rekomendacji utworzonych dla Twojego partnera.
  5. Włącz interfejs API i wygeneruj dane uwierzytelniające. Gdy przedstawiciel potwierdzi, że dostęp został przyznany, włącz interfejs Google TV Video Discovery API (tvvideodiscovery.googleapis.com) w projekcie w chmurze Google i wygeneruj dane logowania OAuth 2.0 dla konta usługi.
  6. Uwierzytelniaj żądania. Poproś o tokeny dostępu OAuth 2.0, używając tego zakresu OAuth, i przekazuj token w nagłówku HTTP Authorization: Bearer przy każdym wywołaniu:

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

Ograniczenia liczby żądań

Żądania wysyłane do replaceCandidates podlegają tym limitom liczby żądań na projekt i limitom ładunku na żądanie:

Limit Wartość
Żądania na minutę na projekt w chmurze Google 5
Żądania dziennie na projekt w chmurze Google Cloud 100
RecommendationCandidate elementów na żądanie 1–25

Żądania dotyczące pliku danych o produktach w środowisku testowym są wliczane do tego samego limitu co żądania dotyczące odpowiedniego pliku danych o produktach w środowisku produkcyjnym.

Pliki danych z rekomendacjami

Interfejs API porządkuje kandydatów do rekomendacji w kanały rekomendacji. Plik danych jest identyfikowany przez nazwę zasobu w tym formacie:

partners/{partner}/recommendationsFeeds/{recommendationsFeed}

Partnerzy

{partner} to identyfikator partnera, który Google przypisuje Ci podczas wprowadzenia. Konto usługi, którego używasz do uwierzytelniania, jest mapowane na dokładnie 1 identyfikator partnera. Żądania, które zawierają nazwę innego partnera, kończą się błędem 403 PERMISSION_DENIED.

Identyfikatory kanałów

{recommendationsFeed} to identyfikator pliku danych, który Google tworzy dla Ciebie podczas procesu wprowadzającego. Nie możesz tworzyć plików danych za pomocą interfejsu API.

Każdy kanał jest kierowany na odbiorców, których Google konfiguruje podczas tworzenia kanału:

  • Kraje lub regiony: miejsca, w których wyświetlają się kandydaci z pliku danych.
  • Języki na telewizorze: języki, które docelowi użytkownicy ustawili na telewizorze. To nie jest język wysyłanego tekstu. Aby podać tekst w więcej niż 1 języku, zapoznaj się z LocalizedString.

Google decyduje, gdzie na urządzeniach z Google TV i Androidem TV będą wyświetlane kandydaty z kanału. Kandydatów wysyła się do wszystkich plików danych w ten sam sposób.

Pliki danych na etapie przejściowym

Każdy kanał ma pasujący kanał przejściowy o nazwie {recommendationsFeed}-staging. Plik danych z przejściowymi danymi jest udostępniany tylko kontom testowym z listy dozwolonych. Użyj go, aby sprawdzić integrację, zanim wyślesz kandydatów do produkcyjnego pliku danych o produktach.

Pliki danych o produktach w trybie przejściowym używają tego samego punktu końcowego, danych logowania, weryfikacji żądań i limitu co pliki danych o produktach w trybie produkcyjnym. Różnią się tylko odbiorcy.

Zamiennik

Plik danych jest jednostką zastępczą. Każde wywołanie replaceCandidates zastępuje wszystkich kandydatów zapisanych wcześniej w tym kanale i nie wpływa na inne kanały.

Zastępowanie kandydatów do rekomendacji

Użyj metody partners.recommendationsFeeds.replaceCandidates, aby wysłać pełną listę kandydatów do rekomendacji dla jednego kanału.

Żądanie HTTP

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

Ścieżka adresu URL zawiera nazwę zasobu pliku danych, którego kandydaci są zastępowani. Treść żądania zawiera wszystkie pola, które nie są częścią ścieżki adresu URL.

Parametry ścieżki

Parametr Opis
name Wymagane. Nazwa zasobu pliku danych w formacie partners/{partner}/recommendationsFeeds/{recommendationsFeed}. {partner} musi być identyfikatorem partnera, do którego jest mapowane Twoje konto usługi. {recommendationsFeed} musi być identyfikatorem pliku danych utworzonym przez Google dla tego partnera lub identyfikatorem pliku danych z przyrostkiem -staging.

ReplaceCandidatesRequest

Treść żądania w formacie JSON ma taką strukturę:

Pole Typ Wymagane Opis
recommendation_candidates array of RecommendationCandidate Tak Lista zawierająca od 1 do 25 elementów RecommendationCandidate. Te kandydatury zastępują obecne kandydatury w kanale.

Schematy kandydujące

Każdy element w recommendation_candidates jest obiektem RecommendationCandidate, który zawiera 1 ładunek typu kandydata, opcjonalne przyczyny rekomendacji i opcjonalne okna dostępności wyświetlania.

RecommendationCandidate

Obiekt RecommendationCandidate zawiera dokładnie jedno pole ładunku typu multimedialnego, opcjonalne przyczyny rekomendacji i opcjonalne przedziały dostępności.

Pole zbiorcze candidate_type

Pole candidate_type jest wymagane: ustaw dokładnie jedno z tych pól. Pola wykluczają się wzajemnie, a kandydat, który nie ustawia żadnego z nich lub ustawia więcej niż jedno, jest odrzucany. W pliku JSON nie ma klucza candidate_type. Ustaw wybrane pole bezpośrednio w obiekcie RecommendationCandidate.

Pole Typ Opis
movie_candidate MovieCandidate film na żądanie (patrz MovieCandidate);
tv_show_candidate TvShowCandidate program telewizyjny na poziomie programu (patrz TvShowCandidate);
live_tv_program_candidate LiveTvProgramCandidate Zaplanowana transmisja telewizyjna na żywo lub wydarzenie transmitowane strumieniowo (zobacz LiveTvProgramCandidate).

Kontekst i dostępność

Oba pola są opcjonalne:

Pole Typ Wymagane Opis
recommendation_contexts array of RecommendationContext Nie dlaczego kandydat jest zalecany i jak długo obowiązuje każde uzasadnienie (patrz RecommendationContext).
availability_intervals array of Interval Nie Przedziały czasu, w których kandydat może być wyświetlany (patrz Interval). Każdy przedział czasu zaczyna się od start_time (włącznie) i kończy się na end_time (wyłącznie). Jeśli nie zostanie ustawiony, kandydat będzie kwalifikował się tak długo, jak będzie przechowywany. Kandydat, którego wszystkie okna są w przeszłości, nigdy nie jest wyświetlany.

MovieCandidate

Obiekt MovieCandidate reprezentuje film na żądanie:

Pole Typ Wymagane Opis
title LocalizedString Tak Tytuł filmu (patrz LocalizedString). Każda wartość to od 1 do 100 punktów kodowych Unicode i jest wyświetlana w postaci, w jakiej została wysłana.
description LocalizedString Tak Krótki opis filmu (patrz LocalizedString). Każda wartość to od 1 do 400 punktów kodowych Unicode.
localized_media_images array of LocalizedMediaImage Tak Grafiki w proporcjach 16:9, po 1 wpisie na język (patrz LocalizedMediaImage). Musi zawierać co najmniej 1 obraz. Prześlij plik źródłowy o największym dostępnym rozmiarze. Zalecamy 1920 x 1080 pikseli.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Tak Precyzyjne linki na platformę i język (patrz LocalizedProviderPlaybackUri). Co najmniej 1 wpis musi zawierać PLATFORM_ANDROID_TV.
release_date Date Tak Data premiery filmu (patrz Date).
external_entity_ids array of ExternalEntityId Nie Zewnętrzne identyfikatory katalogu do dopasowywania encji (patrz ExternalEntityId). Maksymalnie 1 wpis na typ identyfikatora.
duration string (Duration) Nie Czas trwania filmu (patrz Duration). Na przykład "7200s" oznacza 2 godziny.
content_ratings array of ContentRating Nie oficjalne oceny treści (patrz ContentRating);

TvShowCandidate

Obiekt TvShowCandidate reprezentuje program telewizyjny na poziomie programu. Na urządzeniach z Google TV i urządzeniach z Androidem TV wyświetla się karta programu. Użyj precyzyjnego linku, aby zdecydować, czy odtwarzanie ma się rozpoczynać na stronie programu czy na konkretnym odcinku.

Pole Typ Wymagane Opis
title LocalizedString Tak Tytuł programu telewizyjnego (patrz LocalizedString). Każda wartość zawiera od 1 do 100 punktów kodowych Unicode i jest wyświetlana w postaci, w jakiej została wysłana.
description LocalizedString Tak Krótki opis programu telewizyjnego (patrz LocalizedString). Każda wartość to od 1 do 400 punktów kodowych Unicode.
localized_media_images array of LocalizedMediaImage Tak Grafiki w proporcjach 16:9, po 1 wpisie na język (patrz LocalizedMediaImage). Musi zawierać co najmniej 1 obraz. Prześlij plik źródłowy o największym dostępnym rozmiarze. Zalecamy 1920 x 1080 pikseli.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Tak Precyzyjne linki na platformę i język (patrz LocalizedProviderPlaybackUri). Co najmniej 1 wpis musi zawierać PLATFORM_ANDROID_TV. uri może wskazywać stronę programu lub odcinek.
first_episode_air_date Date Tak Data emisji pierwszego odcinka (patrz Date).
external_entity_ids array of ExternalEntityId Nie Zewnętrzne identyfikatory katalogu do dopasowywania encji (patrz ExternalEntityId). Maksymalnie 1 wpis na typ identyfikatora.
season_count integer (32-bitowa liczba całkowita) Nie Liczba sezonów dostępnych w Twojej usłudze.
content_ratings array of ContentRating Nie oficjalne oceny treści (patrz ContentRating);

LiveTvProgramCandidate

Obiekt LiveTvProgramCandidate reprezentuje zaplanowaną transmisję telewizyjną na żywo lub wydarzenie transmitowane strumieniowo. Okno transmisji jest częścią kandydata i jest oddzielone od availability_intervals kandydata nadrzędnego, które kontrolują, kiedy karta może być wyświetlana.

Pole Typ Wymagane Opis
title LocalizedString Tak Tytuł programu telewizyjnego na żywo (patrz LocalizedString). Każda wartość składa się z 1–100 punktów kodowych Unicode i jest wyświetlana w takiej postaci, w jakiej została wysłana.
description LocalizedString Tak Krótki opis programu telewizyjnego na żywo (patrz LocalizedString). Każda wartość to od 1 do 400 punktów kodowych Unicode.
localized_media_images array of LocalizedMediaImage Tak Grafiki w proporcjach 16:9, po 1 wpisie na język (patrz LocalizedMediaImage). Musi zawierać co najmniej 1 obraz. Prześlij plik źródłowy o największym dostępnym rozmiarze. Zalecamy 1920 x 1080 pikseli.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Tak Precyzyjne linki na platformę i język (patrz LocalizedProviderPlaybackUri). Co najmniej 1 wpis musi zawierać PLATFORM_ANDROID_TV.
broadcast_interval Interval Tak Początek i koniec transmisji programu (patrz Interval). Wymagane są zarówno start_time, jak i end_time.
external_entity_ids array of ExternalEntityId Nie Zewnętrzne identyfikatory katalogu do dopasowywania encji (patrz ExternalEntityId). Maksymalnie 1 wpis na typ identyfikatora.
content_ratings array of ContentRating Nie oficjalne oceny treści (patrz ContentRating);

Schematy pomocnicze

Dane kandydujące odwołują się do tych obiektów udostępnionych w przypadku zlokalizowanego tekstu, precyzyjnych linków, grafiki, identyfikatorów zewnętrznych, powodów rekomendacji, interwałów wyświetlania, ocen treści oraz znanych typów daty i godziny.

LocalizedString

Obiekt LocalizedString zawiera ten sam tekst w co najmniej 1 języku. Każda wartość jest oznaczona tagiem języka, dzięki czemu urządzenia Google TV i Android TV mogą wyświetlać tekst zgodny z językiem urządzenia telewizyjnego użytkownika:

Pole Typ Wymagane Opis
values array of LocalizedText Tak Tekst w każdym podanym języku (patrz LocalizedText). Musi zawierać co najmniej 1 wartość.

LocalizedText

Obiekt LocalizedText to tekst w jednym języku:

Pole Typ Wymagane Opis
text string Tak Tekst w języku podanym przez language_code.
language_code string Tak Kod języka text w standardzie BCP-47, np. "en-US" lub "sr-Latn".

LocalizedMediaImage

Obiekt LocalizedMediaImage łączy obraz z językiem tekstu na obrazie:

Pole Typ Wymagane Opis
language_code string Tak Kod języka tekstu na obrazie w standardzie BCP-47, np. "en-US" lub "sr-Latn".
image MediaImage Tak Obraz o proporcjach 16:9 (patrz MediaImage). Prześlij największy dostępny plik źródłowy. Zalecany rozmiar to 1920 x 1080 pikseli.

LocalizedProviderPlaybackUri

Obiekt LocalizedProviderPlaybackUri paruje precyzyjny link z językiem treści, które otwiera, oraz z aplikacją, która je otwiera:

Pole Typ Wymagane Opis
playback_uri PlaybackUri Tak Precyzyjny link i platformy, na których działa (patrz PlaybackUri).
language_code string Tak Kod języka w standardzie BCP-47 treści, które otwiera precyzyjny link, np. "en-US" lub "sr-Latn".
package_name string Tak Nazwa pakietu aplikacji na Androida używana do otwierania precyzyjnego linku (np. "com.example.tvapp").

PlaybackUri

Obiekt PlaybackUri definiuje precyzyjny link i jego platformy docelowe:

Pole Typ Wymagane Opis
uri string Tak Identyfikator URI precyzyjnego linku, który rozpoczyna odtwarzanie kandydata w aplikacji.
platforms array of string (enum) Tak Platformy, do których ma zastosowanie ten precyzyjny link. Dozwolone wartości: PLATFORM_UNSPECIFIED, PLATFORM_ANDROID_TV, PLATFORM_ANDROID oraz PLATFORM_IOS. Uwzględnij PLATFORM_ANDROID_TV na urządzeniach Google TV i Android TV.

MediaImage

Obiekt MediaImage określa adres URL obrazu, jego wymiary w pikselach i tekst ułatwień dostępu:

Pole Typ Wymagane Opis
url string Tak Publicznie dostępny adres URL HTTPS obrazu.
width integer Tak Niezmodyfikowana (maksymalna) szerokość obrazu w pikselach.
height integer Tak Niezmodyfikowana (maksymalna) wysokość obrazu w pikselach.
accessibility_text string Tak Tekst ułatwień dostępu (alternatywny) opisujący obraz.

ExternalEntityId

Obiekt ExternalEntityId mapuje kandydata na identyfikator w katalogu zewnętrznym. Ustaw dokładnie jedno z tych pól na wpis i uwzględnij maksymalnie jeden wpis na typ identyfikatora na liście external_entity_ids kandydata:

Pole Typ Wymagane Opis
tms_root_id string Jedno z tej listy: Identyfikator główny Gracenote TMS. Identyfikuje tytuł: film, program lub odcinek.
tms_id string Jedno z tej listy: Identyfikator wariantu Gracenote TMS. Identyfikuje wydanie lub listę transmisji.
data_feed_element_id string Jedno z tej listy: Identyfikator jednostki z pliku danych Media Actions. Ta wartość nie jest powiązana z segmentem {recommendationsFeed} nazwy zasobu.

RecommendationContext

Obiekt RecommendationContext wyjaśnia, dlaczego kandydat jest zalecany i jak długo to wyjaśnienie obowiązuje:

Pole Typ Wymagane Opis
recommendation_reason RecommendationReason Nie dlaczego kandydat jest polecany (patrz RecommendationReason).
validity_interval Interval Nie Przedział czasu, w którym ten kontekst ma zastosowanie (patrz Interval). Na przykład kandydat jest nowy tylko przez ograniczoną liczbę dni. Jeśli nie jest ustawiony, kontekst obowiązuje tak długo, jak długo przechowywany jest kandydat.

RecommendationReason

Obiekt RecommendationReason zawiera 1 powód. Ustaw dokładnie jedno z tych pól:

Pole Typ Wymagane Opis
top_on_partner object Jedno z tej listy: Kandydat jest najwyżej ocenianym elementem w Twojej usłudze. Zawiera pojedyncze pole z dodatnią liczbą całkowitą rank (np. {"rank": 1} dla „Top 1 on Partner”).
popular_on_partner object Jedno z tej listy: Kandydat jest popularny w Twojej usłudze. Przekaż pusty obiekt ({}).
new_on_partner object Jedno z tej listy: Kandydat jest nowym użytkownikiem Twojej usługi. Przekaż pusty obiekt ({}).
generic object Jedno z tej listy: Przyczyna niestandardowa. Zawiera jedno pole LocalizedString generic_reason (patrz LocalizedString). Każda wartość to od 1 do 100 punktów kodowych Unicode.

ContentRating

Obiekt ContentRating reprezentuje oficjalną ocenę treści przypisaną przez agencję oceniającą:

Pole Typ Wymagane Opis
rating_system string Tak Agencja lub system oceniania, np. "MPAA", "BBFC" lub "CBFC".
rating_value string Tak Ocena zdefiniowana przez rating_system, na przykład "PG-13" lub "U/A 13+".

Timestamp

Wartość Timestamp jest kodowana w formacie JSON jako ciąg znaków RFC 3339 w formacie UTC z sufiksem Z, na przykład "2026-10-01T18:00:00Z". Dozwolone są ułamkowe części sekundy, na przykład "2026-10-01T18:00:00.500Z".

Duration

Wartość Duration jest kodowana w formacie JSON jako ciąg znaków zawierający liczbę sekund, po której następuje sufiks s, np. "7200s" dla 2 godzin. Dozwolone są ułamki sekund, na przykład "5400.5s".

Date

Date to data kalendarzowa bez strefy czasowej. Jest on zakodowany w formacie JSON jako obiekt z tymi polami:

Pole Typ Wymagane Opis
year integer Tak Rok daty, np. 2025.
month integer Nie Miesiąc roku, od 1 do 12. Ustaw wartość 0 lub pomiń, jeśli miesiąc nie jest znany.
day integer Nie Dzień miesiąca od 1 do 31, prawidłowy dla danego roku i miesiąca. Ustaw wartość 0 lub pomiń, jeśli dzień nie jest znany. Wymaga subskrypcji month.

Na przykład {"year": 2025, "month": 1, "day": 17} oznacza 17 stycznia 2025 r., {"year": 2025, "month": 1} oznacza styczeń 2025 r. z nieznanym dniem, a {"year": 2025} oznacza datę w 2025 r. z nieznanym miesiącem i dniem.

Interval

Interval to półotwarty przedział czasu, który zaczyna się o start_time (włącznie) i kończy o end_time (wyłącznie). Czas T mieści się w interwale, gdy start_time <= T i T < end_time.

Pole Typ Wymagane Opis
start_time string (Timestamp) Tak Początek okna (włącznie) (patrz Timestamp), na przykład "2026-10-01T18:00:00Z".
end_time string (Timestamp) Tak Koniec okna (wyłącznie) (patrz Timestamp), na przykład "2026-10-01T21:00:00Z". Musi przypadać później niż start_time.

Przykładowe żądanie

W tym przykładzie zastępujemy kandydatów z kanału in-en-cricket partnera example-partner 3 kandydatami (filmem, serialem i programem telewizyjnym na żywo). Film zawiera tekst w 2 językach:

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"
          }
        ]
      }
    ]
  }'

Zachowanie dotyczące odpowiedzi i zastępowania

W tej sekcji opisujemy odpowiedź HTTP zwracaną przez replaceCandidates i sposób, w jaki każde wywołanie aktualizuje przechowywane informacje o kandydatach.

ReplaceCandidatesResponse

Jeśli żądanie się powiedzie, interfejs API zwróci kod HTTP 200 OK z treścią ReplaceCandidatesResponse:

Pole Typ Opis
replaced_candidates_count integer (32-bitowa liczba całkowita) Liczba zastąpionych kandydatów.

W przypadku poprzedniego przykładowego żądania odpowiedź brzmi:

{
  "replaced_candidates_count": 3
}

Działanie zastępowania

Zrozumienie, jak replaceCandidates aktualizuje przechowywane dane kandydatów, jest kluczowe dla zaprojektowania integracji:

  • Pełne zastąpienie pliku danych. Każde wywołanie całkowicie zastępuje wcześniej zapisaną listę kandydatów dla pliku danych o nazwie podanej w ścieżce adresu URL. Zawsze wysyłaj pełny zestaw aktywnych kandydatów dla tego kanału.
  • Inne pliki danych pozostają bez zmian. Pliki danych, do których nie wysyłasz kandydatów, pozostają niezmienione, dopóki tego nie zrobisz. Na przykład zastąpienie kandydatów w jednym pliku danych nie powoduje zmiany zapisanych kandydatów w żadnym innym pliku danych, a zastąpienie kandydatów w pliku {recommendationsFeed}-staging nie powoduje zmiany pliku {recommendationsFeed}.
  • Jedno wywołanie na plik danych. Aby zaktualizować kilka kanałów, wykonaj jedno wywołanie na kanał. Wywołania są niezależne: jeśli jedno się nie powiedzie, pozostałe kanały zachowają nowych kandydatów, a Ty ponowisz tylko nieudane wywołanie.
  • Przesyłaj ponownie aktywne pliki danych co najmniej raz na 30 dni. Nawet jeśli katalog dla pliku danych nie uległ zmianie, przesyłaj ponownie każdy aktywny plik danych co najmniej raz na 30 dni (lub zgodnie z regularnym harmonogramem dziennym lub tygodniowym z losowym jitterem), aby kandydaci pozostali aktywni i nie wygasali. Ustawienie daty availability_intervals end_time daleko w przyszłości nie zastępuje okresowego ponownego wysyłania.
  • Wykonywanie niepodzielne. Interfejs API stosuje żądanie niepodzielnie. Jeśli którykolwiek z kandydatów nie przejdzie weryfikacji, interfejs API odrzuci całe żądanie, a w pliku danych pozostaną poprzedni kandydaci.