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:
- Utwórz konto Google Workspace. Postępuj zgodnie z instrukcjami na stronie pomocy Google Workspace, aby skonfigurować konto dla swojej organizacji.
- Znajdź identyfikator klienta Google Workspace. Znajdź swój identyfikator klienta (np.
C0123abcd), wykonując czynności opisane w artykule Znajdowanie identyfikatora klienta. - 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.
- 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.
- 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. Uwierzytelniaj żądania. Poproś o tokeny dostępu OAuth 2.0, używając tego zakresu OAuth, i przekazuj token w nagłówku HTTP
Authorization: Bearerprzy 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}-stagingnie 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_intervalsend_timedaleko 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.