Mit der Google TV Video Discovery REST API können Partner nicht personalisierte Empfehlungskandidaten von ihren Backend-Servern an Google TV- und Android TV-Geräte senden. Wenn Kandidaten aus dem Backend gesendet werden, bleiben der Katalog und die Empfehlungen für Live-Programme eines Partners auf diesen Geräten aktuell, ohne dass Nutzer die App des Partners öffnen müssen.
Partner senden Kandidaten an Empfehlungsfeeds. Google erstellt jeden Feed für den Partner und konfiguriert die Länder oder Regionen und die Sprachen der TV-Geräte, für die der Feed angezeigt wird. Ein Feed kann Filme, Serien und Live-TV-Sendungen enthalten.
Wenn du personalisierte Empfehlungen vom Gerät des Nutzers veröffentlichen möchtest, lies den Hilfeartikel Empfehlungen auf dem Gerät mit dem Engage SDK einbinden.
Vorbereitung
Bevor Sie die REST API einbinden, benötigen Sie Folgendes:
- Ein Google Cloud-Projekt, von dem aus API-Anfragen gestellt werden.
- Ein Google Workspace-Konto, das mit Ihrer Organisation verknüpft ist.
- Ihre Partner-ID und die IDs der Empfehlungsfeeds, die Sie während der Einrichtung von Ihrem Google TV-Partnervertreter erhalten haben. Weitere Informationen zur Verwendung dieser IDs finden Sie unter Empfehlungsfeeds.
Zugriff holen
Der Zugriff auf die Google TV Video Discovery REST API ist auf registrierte Google TV-Medienpartner beschränkt. Jeder Aufrufer wird mit einem Google Cloud-Dienstkonto authentifiziert, das auf dem Server genau einer Partner-ID zugeordnet ist.
So fordern Sie den API-Zugriff an und konfigurieren ihn:
- Google Workspace-Konto erstellen Folgen Sie der Anleitung auf der Google Workspace-Supportseite, um ein Konto für Ihre Organisation einzurichten.
- Google Workspace-Kundennummer ermitteln Suchen Sie Ihre Kundennummer (z. B.
C0123abcd). Folgen Sie dazu der Anleitung unter Kundennummer suchen. - Google Cloud-Projekt und -Dienstkonto erstellen Erstellen Sie in der Google Cloud Console unter Ihrer Google Workspace-Organisation ein Google Cloud-Projekt und ein Dienstkonto für Ihren Backend-Server.
- Onboarding von Partnern anfordern Gib deine Google Workspace-Kundennummer, deine Google Cloud-Projekt-ID und die E-Mail-Adresse deines Dienstkontos (oder die eindeutige numerische ID) an deinen Google TV-Partnervertreter weiter. Gib außerdem die Länder oder Regionen und die Sprachen der TV-Geräte an, an die du Kandidaten senden möchtest. Dein Google TV-Partnervertreter benachrichtigt dich, nachdem er deine Google Workspace-Organisation, dein Projekt und dein Dienstkonto deiner Partner-ID zugeordnet hat, und teilt dir die für deinen Partner erstellten IDs für den Empfehlungsfeed mit.
- Aktivieren Sie die API und generieren Sie Anmeldedaten. Nachdem Ihr Ansprechpartner den Zugriff bestätigt hat, aktivieren Sie die Google TV Video Discovery API (
tvvideodiscovery.googleapis.com) in Ihrem Google Cloud-Projekt und generieren Sie OAuth 2.0-Anmeldedaten für Ihr Dienstkonto. Anfragen authentifizieren Fordern Sie OAuth 2.0-Zugriffstokens mit dem folgenden OAuth-Bereich an und übergeben Sie das Token bei jedem Aufruf im HTTP-Header
Authorization: Bearer:https://www.googleapis.com/auth/tvvideodiscovery
Ratenlimits
Anfragen an replaceCandidates unterliegen den folgenden projektbezogenen Ratenbegrenzungen und Nutzlastbeschränkungen pro Anfrage:
| Limit | Wert |
|---|---|
| Anfragen pro Minute und Google Cloud-Projekt | 5 |
| Anfragen pro Tag und Google Cloud-Projekt | 100 |
RecommendationCandidate Elemente pro Anfrage |
1 bis 25 |
Anfragen an einen Staging-Feed werden auf dasselbe Kontingent angerechnet wie Anfragen an den entsprechenden Produktionsfeed.
Empfehlungsfeeds
Die API organisiert Empfehlungskandidaten in Empfehlungsfeeds. Ein Feed wird durch einen Ressourcennamen im folgenden Format identifiziert:
partners/{partner}/recommendationsFeeds/{recommendationsFeed}
Partner
{partner} ist die Partner-ID, die Google Ihnen während der Einrichtung zuweist. Das Dienstkonto, mit dem Sie sich authentifizieren, ist genau einer Partner-ID zugeordnet.
Anfragen, die einen anderen Partner nennen, schlagen mit 403 PERMISSION_DENIED fehl.
Feed-IDs
{recommendationsFeed} ist eine Feed-ID, die Google während des Onboardings für Sie erstellt. Sie können keine Feeds mit der API erstellen.
Jeder Feed richtet sich an eine Zielgruppe, die von Google beim Erstellen des Feeds konfiguriert wird:
- Länder oder Regionen: Hier werden die Kandidaten des Feeds angezeigt.
- Sprachen von TV-Geräten: Die Sprachen, die die Zielnutzer auf ihrem TV-Gerät eingestellt haben. Dies ist nicht die Sprache des Textes, den Sie senden. Wenn Sie Text in mehreren Sprachen bereitstellen möchten, lesen Sie den Abschnitt
LocalizedString.
Google entscheidet, wo die Kandidaten eines Feeds auf Google TV- und Android TV-Geräten angezeigt werden. Sie senden Kandidaten auf dieselbe Weise an alle Feeds.
Staging-Feeds
Jeder Feed hat einen entsprechenden Staging-Feed mit dem Namen {recommendationsFeed}-staging. Ein Staging-Feed wird nur für Testkonten auf einer Zulassungsliste bereitgestellt. Verwenden Sie sie, um Ihre Integration zu validieren, bevor Sie Kandidaten an den Produktionsfeed senden.
Staging-Feeds verwenden denselben Endpunkt, dieselben Anmeldedaten, dieselbe Anfragevalidierung und dasselbe Kontingent wie Produktionsfeeds. Nur die Zielgruppe ist eine andere.
Ersetzen
Der Feed ist die Ersetzungseinheit. Mit jedem replaceCandidates-Aufruf werden alle zuvor für diesen Feed gespeicherten Kandidaten ersetzt. Alle anderen Feeds bleiben unverändert.
Empfehlungskandidaten ersetzen
Verwenden Sie die Methode partners.recommendationsFeeds.replaceCandidates, um die vollständige Liste der Empfehlungskandidaten für einen Feed zu senden.
HTTP-Anfrage
POST https://tvvideodiscovery.googleapis.com/v1/{name=partners/*/recommendationsFeeds/*}:replaceCandidates
Der URL-Pfad enthält den Ressourcennamen des Feeds, dessen Kandidaten ersetzt werden. Der Anfragetext enthält alle Felder, die nicht Teil des URL-Pfads sind.
Pfadparameter
| Parameter | Beschreibung |
|---|---|
name |
Erforderlich. Der Ressourcenname des Feeds im Format partners/{partner}/recommendationsFeeds/{recommendationsFeed}. {partner} muss die Partner-ID sein, der Ihr Dienstkonto zugeordnet ist. {recommendationsFeed} muss eine Feed-ID sein, die Google für diesen Partner erstellt hat, oder diese Feed-ID mit dem Suffix -staging. |
ReplaceCandidatesRequest
Der JSON-Anfragetext hat die folgende Struktur:
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
recommendation_candidates |
array of RecommendationCandidate |
Ja | Eine Liste mit 1 bis 25 RecommendationCandidate-Elementen. Diese Kandidaten ersetzen die aktuellen Kandidaten des Feeds. |
Kandidatenschemas
Jedes Element in recommendation_candidates ist ein RecommendationCandidate-Objekt, das eine Nutzlast vom Typ „candidate“ enthält, optionale Empfehlungsgründe und optionale Verfügbarkeitszeiträume für die Anzeige.
RecommendationCandidate
Ein RecommendationCandidate-Objekt enthält genau ein Nutzlastfeld für den Medientyp, optionale Empfehlungsgründe und optionale Verfügbarkeitsintervalle.
Union-Feld candidate_type
candidate_type ist erforderlich: Legen Sie genau eines der folgenden Felder fest. Die Felder schließen sich gegenseitig aus. Ein Kandidat, der keines oder mehr als eines festlegt, wird abgelehnt. In der JSON-Datei ist kein candidate_type-Schlüssel vorhanden. Legen Sie das ausgewählte Feld direkt im RecommendationCandidate-Objekt fest.
| Feld | Typ | Beschreibung |
|---|---|---|
movie_candidate |
MovieCandidate |
Ein On-Demand-Film (siehe MovieCandidate). |
tv_show_candidate |
TvShowCandidate |
Eine TV-Sendung auf Sendungsebene (siehe TvShowCandidate). |
live_tv_program_candidate |
LiveTvProgramCandidate |
Eine geplante Live-TV-Übertragung oder ein gestreamtes Ereignis (siehe LiveTvProgramCandidate). |
Kontext und Verfügbarkeit
Beide Felder sind optional:
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
recommendation_contexts |
array of RecommendationContext |
Nein | Warum der Kandidat empfohlen wird und wie lange jeder Grund gilt (siehe RecommendationContext). |
availability_intervals |
array of Interval |
Nein | Zeiträume, in denen der Kandidat angezeigt werden kann (siehe Interval). Jeder Zeitraum beginnt bei start_time (einschließlich) und endet bei end_time (ausschließlich). Wenn kein Wert festgelegt ist, ist der Kandidat so lange aktiv, wie er gespeichert ist. Ein Kandidat, dessen Zeitfenster alle in der Vergangenheit liegen, wird nie angezeigt. |
MovieCandidate
Das MovieCandidate-Objekt stellt einen On-Demand-Film dar:
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
title |
LocalizedString |
Ja | Titel des Films (siehe LocalizedString). Jeder Wert besteht aus 1 bis 100 Unicode-Codepunkten und wird so angezeigt, wie er gesendet wurde. |
description |
LocalizedString |
Ja | Kurze Beschreibung des Films (siehe LocalizedString). Jeder Wert umfasst 1 bis 400 Unicode-Codepunkte. |
localized_media_images |
array of LocalizedMediaImage |
Ja | Grafiken im Format 16:9, ein Eintrag pro Sprache (siehe LocalizedMediaImage). Muss mindestens ein Bild enthalten. Stellen Sie die größte verfügbare Quelle bereit. Empfohlen werden 1920 × 1080 Pixel. |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
Ja | Deeplinks pro Plattform und Sprache (siehe LocalizedProviderPlaybackUri). Mindestens ein Eintrag muss PLATFORM_ANDROID_TV enthalten. |
release_date |
Date |
Ja | Veröffentlichungsdatum des Films (siehe Date). |
external_entity_ids |
array of ExternalEntityId |
Nein | Externe Katalogkennungen für den Entitätsabgleich (siehe ExternalEntityId). Maximal ein Eintrag pro Kennungstyp. |
duration |
string (Duration) |
Nein | Wie lange der Film dauert (siehe Duration). Beispiel: "7200s" für 2 Stunden. |
content_ratings |
array of ContentRating |
Nein | Offizielle Altersfreigaben (siehe ContentRating). |
TvShowCandidate
Das Objekt TvShowCandidate stellt eine TV-Sendung auf Sendungsebene dar. Auf Google TV- und Android TV-Geräten wird eine Karte für die Serie angezeigt. Über den Deeplink kannst du festlegen, ob die Wiedergabe auf der Seite der Serie oder bei einer bestimmten Folge beginnt.
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
title |
LocalizedString |
Ja | Titel der TV-Sendung (siehe LocalizedString). Jeder Wert besteht aus 1 bis 100 Unicode-Codepunkten und wird so angezeigt, wie er gesendet wurde. |
description |
LocalizedString |
Ja | Kurzbeschreibung der Serie (siehe LocalizedString). Jeder Wert umfasst 1 bis 400 Unicode-Codepunkte. |
localized_media_images |
array of LocalizedMediaImage |
Ja | Grafiken im Format 16:9, ein Eintrag pro Sprache (siehe LocalizedMediaImage). Muss mindestens ein Bild enthalten. Stellen Sie die größte verfügbare Quelle bereit. Empfohlen werden 1920 × 1080 Pixel. |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
Ja | Deeplinks pro Plattform und Sprache (siehe LocalizedProviderPlaybackUri). Mindestens ein Eintrag muss PLATFORM_ANDROID_TV enthalten. Die uri kann auf die Seite der Serie oder auf eine Folge verweisen. |
first_episode_air_date |
Date |
Ja | Ausstrahlungsdatum der ersten Folge (siehe Date). |
external_entity_ids |
array of ExternalEntityId |
Nein | Externe Katalogkennungen für den Entitätsabgleich (siehe ExternalEntityId). Maximal ein Eintrag pro Kennungstyp. |
season_count |
integer (int32) |
Nein | Anzahl der Staffeln, die in Ihrem Dienst verfügbar sind. |
content_ratings |
array of ContentRating |
Nein | Offizielle Altersfreigaben (siehe ContentRating). |
LiveTvProgramCandidate
Das LiveTvProgramCandidate-Objekt stellt eine geplante Live-TV-Übertragung oder ein gestreamtes Ereignis dar. Das Übertragungsfenster ist Teil des Kandidaten und ist von den availability_intervals des übergeordneten Kandidaten getrennt, die steuern, wann die Karte angezeigt werden darf.
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
title |
LocalizedString |
Ja | Titel der Live-TV-Sendung (siehe LocalizedString). Jeder Wert besteht aus 1 bis 100 Unicode-Codepunkten und wird so angezeigt, wie er gesendet wurde. |
description |
LocalizedString |
Ja | Kurze Beschreibung des Live-TV-Programms (siehe LocalizedString). Jeder Wert umfasst 1 bis 400 Unicode-Codepunkte. |
localized_media_images |
array of LocalizedMediaImage |
Ja | Grafiken im Format 16:9, ein Eintrag pro Sprache (siehe LocalizedMediaImage). Muss mindestens ein Bild enthalten. Stellen Sie die größte verfügbare Quelle bereit. Empfohlen werden 1920 × 1080 Pixel. |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
Ja | Deeplinks pro Plattform und Sprache (siehe LocalizedProviderPlaybackUri). Mindestens ein Eintrag muss PLATFORM_ANDROID_TV enthalten. |
broadcast_interval |
Interval |
Ja | Beginn und Ende der Ausstrahlung des Programms (siehe Interval). Sowohl start_time als auch end_time sind erforderlich. |
external_entity_ids |
array of ExternalEntityId |
Nein | Externe Katalogkennungen für den Entitätsabgleich (siehe ExternalEntityId). Maximal ein Eintrag pro Kennungstyp. |
content_ratings |
array of ContentRating |
Nein | Offizielle Altersfreigaben (siehe ContentRating). |
Unterstützende Schemas
Die Kandidaten-Nutzlasten verweisen auf die folgenden freigegebenen Objekte für lokalisierten Text, Deeplinks, Grafiken, externe Kennungen, Empfehlungsgründe, Anzeigeintervalle, Altersfreigaben und bekannte Datums- und Uhrzeittypen.
LocalizedString
Das LocalizedString-Objekt enthält denselben Text in einer oder mehreren Sprachen.
Jeder Wert ist mit seiner Sprache getaggt, damit Google TV- und Android TV-Geräte den Text anzeigen können, der der Sprache des TV-Geräts des Nutzers entspricht:
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
values |
array of LocalizedText |
Ja | Der Text in jeder von Ihnen angegebenen Sprache (siehe LocalizedText). Muss mindestens einen Wert enthalten. |
LocalizedText
Das LocalizedText-Objekt ist Text in einer einzelnen Sprache:
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
text |
string |
Ja | Der Text in der durch language_code angegebenen Sprache. |
language_code |
string |
Ja | BCP-47-Sprachcode von text, z. B. "en-US" oder "sr-Latn". |
LocalizedMediaImage
Das LocalizedMediaImage-Objekt verknüpft ein Bild mit der Sprache des Texts im Bild:
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
language_code |
string |
Ja | BCP-47-Sprachcode des Texts im Bild, z. B. "en-US" oder "sr-Latn". |
image |
MediaImage |
Ja | Ein Bild im Format 16:9 (siehe MediaImage). Stellen Sie die größte verfügbare Quelle bereit. Empfohlen werden 1920 × 1080 Pixel. |
LocalizedProviderPlaybackUri
Das LocalizedProviderPlaybackUri-Objekt verknüpft einen Deeplink mit der Sprache des Inhalts, den er öffnet, und der App, die ihn öffnet:
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
playback_uri |
PlaybackUri |
Ja | Der Deeplink und die Plattformen, für die er gilt (siehe PlaybackUri). |
language_code |
string |
Ja | BCP-47-Sprachcode des Inhalts, der über den Deeplink geöffnet wird, z. B. "en-US" oder "sr-Latn". |
package_name |
string |
Ja | Name des Android-Anwendungspakets, das zum Öffnen des Deeplinks verwendet wird (z. B. "com.example.tvapp"). |
PlaybackUri
Das Objekt PlaybackUri definiert einen Deeplink und seine Zielplattformen:
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
uri |
string |
Ja | Deeplink-URI, über die die Wiedergabe des Kandidaten in Ihrer App gestartet wird. |
platforms |
array of string (enum) |
Ja | Plattformen, für die dieser Deeplink gilt. Zulässige Werte: PLATFORM_UNSPECIFIED, PLATFORM_ANDROID_TV, PLATFORM_ANDROID, PLATFORM_IOS. Füge PLATFORM_ANDROID_TV für Google TV- und Android TV-Geräte hinzu. |
MediaImage
Das MediaImage-Objekt gibt eine Bild-URL, die Pixelabmessungen und den Text für die Barrierefreiheit an:
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
url |
string |
Ja | Öffentlich zugängliche HTTPS-URL des Bildes. |
width |
integer |
Ja | Unveränderte (maximale) Bildbreite in Pixeln. |
height |
integer |
Ja | Unveränderte (maximale) Bildhöhe in Pixeln. |
accessibility_text |
string |
Ja | Alt-Text für Barrierefreiheit, der das Bild beschreibt. |
ExternalEntityId
Das Objekt ExternalEntityId ordnet einen Kandidaten einer Kennung in einem externen Katalog zu. Legen Sie pro Eintrag genau eines der folgenden Felder fest und fügen Sie höchstens einen Eintrag pro Kennungstyp in die external_entity_ids-Liste eines Kandidaten ein:
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
tms_root_id |
string |
Eine von | Gracenote-TMS-Root-ID. Kennzeichnet einen Titel: einen Film, eine Serie oder eine Folge. |
tms_id |
string |
Eine von | Gracenote-TMS-Varianten-ID. Kennzeichnet eine Ausgabe oder einen Sendeeintrag. |
data_feed_element_id |
string |
Eine von | Entitäts-ID aus Ihrem Datenfeed für Media Actions. Dieser Wert steht nicht im Zusammenhang mit dem {recommendationsFeed}-Segment des Ressourcennamens. |
RecommendationContext
Das Objekt RecommendationContext erklärt, warum ein Kandidat empfohlen wird und wie lange diese Erklärung gilt:
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
recommendation_reason |
RecommendationReason |
Nein | Warum der Kandidat empfohlen wird (siehe RecommendationReason). |
validity_interval |
Interval |
Nein | Zeitraum, in dem dieser Kontext gilt (siehe Interval). Ein Kandidat ist beispielsweise nur für eine begrenzte Anzahl von Tagen neu. Wenn nicht festgelegt, gilt der Kontext so lange, wie der Kandidat gespeichert ist. |
RecommendationReason
Das RecommendationReason-Objekt enthält einen Grund. Legen Sie genau eines der folgenden Felder fest:
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
top_on_partner |
object |
Eine von | Der Kandidat ist ein hochrangiges Element in Ihrem Dienst. Enthält ein einzelnes positives Ganzzahlfeld rank (z. B. {"rank": 1} für „Top 1 auf Partner“). |
popular_on_partner |
object |
Eine von | Der Kandidat ist in Ihrem Dienst beliebt. Übergeben Sie ein leeres Objekt ({}). |
new_on_partner |
object |
Eine von | Der Kandidat ist neu bei Ihrem Dienst. Übergeben Sie ein leeres Objekt ({}). |
generic |
object |
Eine von | Ein benutzerdefinierter Grund. Enthält ein einzelnes LocalizedString-Feld generic_reason (siehe LocalizedString). Jeder Wert besteht aus 1 bis 100 Unicode-Codepunkten. |
ContentRating
Das Objekt ContentRating stellt eine offizielle Altersfreigabe dar, die von einer Einstufungsstelle zugewiesen wurde:
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
rating_system |
string |
Ja | Ratingagentur oder -system, z. B. "MPAA", "BBFC" oder "CBFC". |
rating_value |
string |
Ja | Bewertung gemäß rating_system, z. B. "PG-13" oder "U/A 13+". |
Timestamp
Ein Timestamp wird in JSON als RFC 3339-String in UTC mit dem Suffix Z codiert, z. B. "2026-10-01T18:00:00Z". Sekundenbruchteile sind zulässig, z. B. "2026-10-01T18:00:00.500Z".
Duration
Ein Duration wird in JSON als String codiert, der die Anzahl der Sekunden gefolgt vom Suffix s enthält, z. B. "7200s" für 2 Stunden. Sekundenbruchteile sind zulässig, z. B. "5400.5s".
Date
Ein Date ist ein Kalenderdatum ohne Zeitzone. Es wird in JSON als Objekt mit den folgenden Feldern codiert:
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
year |
integer |
Ja | Jahr des Datums, z. B. 2025. |
month |
integer |
Nein | Monat des Jahres, von 1 bis 12. Legen Sie 0 fest oder lassen Sie den Wert weg, wenn der Monat nicht bekannt ist. |
day |
integer |
Nein | Tag des Monats, von 1 bis 31, und gültig für das angegebene Jahr und den angegebenen Monat. Legen Sie den Wert auf 0 fest oder lassen Sie ihn weg, wenn der Tag nicht bekannt ist. month erforderlich. |
Beispiel: {"year": 2025, "month": 1, "day": 17} steht für den 17. Januar 2025, {"year": 2025, "month": 1} für Januar 2025 mit unbekanntem Tag und {"year": 2025} für ein Datum im Jahr 2025 mit unbekanntem Monat und Tag.
Interval
Ein Interval ist ein halboffenes Zeitfenster, das bei start_time (einschließlich) beginnt und bei end_time (ausschließlich) endet. Ein Zeitpunkt T liegt innerhalb des Intervalls, wenn start_time <= T und T < end_time.
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
start_time |
string (Timestamp) |
Ja | Eingeschlossener Start des Zeitfensters (siehe Timestamp), z. B. "2026-10-01T18:00:00Z". |
end_time |
string (Timestamp) |
Ja | Ausgeschlossenes Ende des Zeitfensters (siehe Timestamp), z. B. "2026-10-01T21:00:00Z". Muss nach start_time liegen. |
Beispielanfrage
Im folgenden Beispiel werden die Kandidaten des Feeds in-en-cricket des Partners example-partner durch drei Kandidaten ersetzt (ein Film, eine Serie und ein Live-TV-Programm). Der Film enthält Text in zwei Sprachen:
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"
}
]
}
]
}'
Antwort- und Ersetzungsverhalten
In diesem Abschnitt wird die von replaceCandidates zurückgegebene HTTP-Antwort beschrieben und wie jeder Aufruf Ihre gespeicherten Kandidaten aktualisiert.
ReplaceCandidatesResponse
Wenn die Anfrage erfolgreich ist, gibt die API HTTP 200 OK mit einem ReplaceCandidatesResponse-Text zurück:
| Feld | Typ | Beschreibung |
|---|---|---|
replaced_candidates_count |
integer (int32) |
Anzahl der ersetzten Kandidaten. |
Für die vorherige Beispielanfrage lautet die Antwort:
{
"replaced_candidates_count": 3
}
Ersetzungsverhalten
Für die Integration ist es wichtig zu verstehen, wie replaceCandidates gespeicherte Kandidaten aktualisiert:
- Vollständiger Ersatz pro Feed. Bei jedem Aufruf wird die zuvor gespeicherte Kandidatenliste für den im URL-Pfad angegebenen Feed vollständig ersetzt. Senden Sie immer den vollständigen Satz aktiver Kandidaten für diesen Feed.
- Andere Feeds bleiben unverändert. Feeds, an die Sie keine Kandidaten senden, bleiben unverändert, bis Sie dies tun. Wenn Sie beispielsweise die Kandidaten eines Feeds ersetzen, werden die gespeicherten Kandidaten für andere Feeds nicht geändert. Wenn Sie die Kandidaten von
{recommendationsFeed}-stagingersetzen, wird{recommendationsFeed}nicht geändert. - Ein Aufruf pro Feed. Wenn Sie mehrere Feeds aktualisieren möchten, führen Sie einen Aufruf pro Feed aus. Die Aufrufe sind unabhängig voneinander: Wenn einer fehlschlägt, behalten die anderen Feeds ihre neuen Kandidaten und Sie wiederholen nur den fehlgeschlagenen Aufruf.
- Senden Sie aktive Feeds mindestens alle 30 Tage neu. Auch wenn sich der Katalog für einen Feed nicht geändert hat, sollten Sie jeden aktiven Feed mindestens alle 30 Tage (oder regelmäßig täglich oder wöchentlich mit zufälligem Jitter) noch einmal senden, damit Ihre Kandidaten aktiv bleiben und nicht ablaufen. Wenn Sie einen
availability_intervals-end_timeweit in der Zukunft festlegen, wird das regelmäßige erneute Senden nicht ersetzt. - Atomare Ausführung. Die API wendet die Anfrage atomar an. Wenn ein Kandidat die Validierung nicht besteht, lehnt die API die gesamte Anfrage ab und der Feed behält seine vorherigen Kandidaten bei.