合作夥伴可透過 Google TV Video Discovery REST API,從後端伺服器將非個人化推薦候選項目傳送至 Google TV 和 Android TV 裝置。從後端傳送候選項目,可讓合作夥伴的目錄和直播節目推薦內容在這些裝置上保持最新狀態,使用者不必開啟合作夥伴的應用程式。
合作夥伴會將候選項目傳送至推薦動態饋給。Google 會為合作夥伴建立各個動態饋給,並設定動態饋給顯示的國家/地區和電視裝置語言。動態饋給可包含電影、電視節目和電視直播節目。
如要從使用者裝置發布個人化推薦內容,請參閱「使用 Engage SDK 整合裝置端推薦內容」。
必要條件
與 REST API 整合前,請確認您具備下列項目:
- 用於提出 API 要求的 Google Cloud 專案。
- 與貴組織相關聯的 Google Workspace 帳戶。
- 合作夥伴 ID 和推薦內容動態饋給 ID,由 Google TV 合作夥伴代表在新手上路期間提供。如要瞭解這些 ID 的使用方式,請參閱「建議動態饋給」。
取得會員權益
只有註冊的 Google TV 媒體合作夥伴,才能存取 Google TV Video Discovery REST API。系統會使用 Google Cloud 服務帳戶驗證每位呼叫者,該帳戶在伺服器上會對應至一個合作夥伴 ID。
如要申請及設定 API 存取權,請按照下列步驟操作:
- 建立 Google Workspace 帳戶。請按照 Google Workspace 支援頁面上的操作說明,為貴機構設定帳戶。
- 找出 Google Workspace 客戶 ID。按照「查看您的客戶 ID」一文中的步驟,找出您的客戶 ID (例如
C0123abcd)。 - 建立 Google Cloud 雲端專案和服務帳戶。在 Google Workspace 組織下的 Google Cloud 控制台中,建立 Google Cloud 專案和後端伺服器的服務帳戶。
- 要求合作夥伴新手上路。請將 Google Workspace 客戶 ID、Google Cloud 專案 ID 和服務帳戶電子郵件地址 (或不重複數字 ID) 提供給 Google TV 合作夥伴代表,並附上要傳送候選內容的國家/地區和電視裝置語言。Google TV 合作夥伴代表將 Google Workspace 機構、專案和服務帳戶對應至合作夥伴 ID 後,會通知您,並提供為合作夥伴建立的推薦內容動態饋給 ID。
- 啟用 API 並產生憑證。代表確認已授予存取權後,請在 Google Cloud 雲端專案中啟用 Google TV Video Discovery API (
tvvideodiscovery.googleapis.com),並為服務帳戶產生 OAuth 2.0 憑證。 驗證要求。使用下列 OAuth 範圍要求 OAuth 2.0 存取權杖,並在每次呼叫時,透過
Authorization: BearerHTTP 標頭傳遞權杖:https://www.googleapis.com/auth/tvvideodiscovery
頻率限制
對 replaceCandidates 的要求須遵守下列每項專案的頻率限制,以及每項要求的酬載上限:
| 限制 | 值 |
|---|---|
| 每項 Google Cloud 雲端專案每分鐘的要求數 | 5 |
| 每個 Google Cloud 雲端專案每日要求數 | 100 |
每次要求 RecommendationCandidate 個項目 |
1 至 25 |
對測試動態饋給提出的要求,會與對應的正式動態饋給要求共用配額。
推薦內容動態饋給
API 會將候選推薦項目整理成推薦動態饋給。動態饋給會以資源名稱識別,格式如下:
partners/{partner}/recommendationsFeeds/{recommendationsFeed}
合作夥伴
{partner} 是 Google 在新手上路期間指派給您的合作夥伴 ID。您用來驗證的服務帳戶只會對應至一個合作夥伴 ID。如果要求指定其他合作夥伴,則會失敗並顯示 403 PERMISSION_DENIED。
動態饋給 ID
{recommendationsFeed} 是 Google 在新手上路期間為您建立的動態饋給 ID。無法透過 API 建立動態饋給。
每個動態饋給都會指定 Google 在建立動態饋給時設定的目標對象:
- 國家/地區:動態饋給候選項目顯示的位置。
- 電視裝置語言:目標使用者在電視裝置上設定的語言。這不是你傳送的文字語言。如要提供多種語言的文字,請參閱
LocalizedString。
Google 會決定動態饋給候選項目在 Google TV 和 Android TV 裝置上的顯示位置。您會以相同方式將候選項目傳送至每個動態饋給。
測試動態饋給
每個動態饋給都有相符的測試動態饋給,名為 {recommendationsFeed}-staging。測試動態饋給只會提供給許可清單中的測試帳戶。請先使用這項工具驗證整合,再將候選項目傳送至正式版動態饋給。
測試動態饋給使用的端點、憑證、要求驗證和配額,與正式動態饋給相同。只有目標對象不同。
替換
動態饋給是替換單位。每次呼叫 replaceCandidates 都會取代先前為該動態饋給儲存的所有候選項目,並保留所有其他動態饋給。
替換建議候選項目
使用 partners.recommendationsFeeds.replaceCandidates 方法,傳送一個動態饋給的完整推薦候選項目清單。
HTTP 要求
POST https://tvvideodiscovery.googleapis.com/v1/{name=partners/*/recommendationsFeeds/*}:replaceCandidates
網址路徑包含要替換候選項目的動態饋給資源名稱。要求主體包含不屬於網址路徑的所有欄位。
路徑參數
| 參數 | 說明 |
|---|---|
name |
必要項目。動態饋給的資源名稱,格式為 partners/{partner}/recommendationsFeeds/{recommendationsFeed}。{partner} 必須是服務帳戶對應的合作夥伴 ID。{recommendationsFeed} 必須是 Google 為該合作夥伴建立的動態饋給 ID,或加上 -staging 後置字串的動態饋給 ID。 |
ReplaceCandidatesRequest
JSON 要求主體的結構如下:
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
recommendation_candidates |
array of RecommendationCandidate |
是 | 1 到 25 個 RecommendationCandidate 項目的清單。這些候選項目會取代動態饋給目前的候選項目。 |
候選結構定義
recommendation_candidates 中的每個項目都是 RecommendationCandidate 物件,包含一個候選類型酬載、選用的推薦原因,以及選用的顯示播映時段。
RecommendationCandidate
RecommendationCandidate 物件包含一個媒體類型酬載欄位、選用的推薦原因,以及選用的供應時間間隔。
聯集欄位 candidate_type
必須提供 candidate_type:請設定下列其中一個欄位。這些欄位互斥,如果候選項目未設定任何欄位或設定多個欄位,就會遭到拒絕。JSON 中沒有 candidate_type 鍵,請直接在 RecommendationCandidate 物件上設定所選欄位。
| 欄位 | 類型 | 說明 |
|---|---|---|
movie_candidate |
MovieCandidate |
隨選電影 (請參閱 MovieCandidate)。 |
tv_show_candidate |
TvShowCandidate |
節目層級的電視節目 (請參閱 TvShowCandidate)。 |
live_tv_program_candidate |
LiveTvProgramCandidate |
排定的電視直播或串流活動 (請參閱 LiveTvProgramCandidate)。 |
背景資訊和適用範圍
這兩個欄位均為選填:
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
recommendation_contexts |
array of RecommendationContext |
否 | 推薦候選人的原因,以及各原因的適用時間長度 (請參閱 RecommendationContext)。 |
availability_intervals |
array of Interval |
否 | 可能顯示候選項目的時間範圍 (請參閱 Interval)。每個時間範圍的開始時間為 start_time (含),結束時間為 end_time (不含)。如未設定,只要候選項目仍儲存在系統中,就符合資格。如果候選廣告的所有時段都已過去,則一律不會顯示。 |
MovieCandidate
MovieCandidate 物件代表隨選電影:
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
title |
LocalizedString |
是 | 電影名稱 (請參閱 LocalizedString)。每個值為 1 到 100 個 Unicode 碼點,並會依傳送時的格式顯示。 |
description |
LocalizedString |
是 | 電影簡短說明 (請參閱 LocalizedString)。每個值為 1 到 400 個 Unicode 碼點。 |
localized_media_images |
array of LocalizedMediaImage |
是 | 16:9 圖片,每種語言一個項目 (請參閱 LocalizedMediaImage)。至少須包含一張圖片。請提供最大可用來源,建議為 1920x1080 像素。 |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
是 | 每個平台和每種語言的深層連結 (請參閱 LocalizedProviderPlaybackUri)。至少一個項目必須列出 PLATFORM_ANDROID_TV。 |
release_date |
Date |
是 | 電影上映日期 (請參閱 Date)。 |
external_entity_ids |
array of ExternalEntityId |
否 | 用於實體比對的外部目錄 ID (請參閱 ExternalEntityId)。每個 ID 類型最多只能有一個項目。 |
duration |
string (Duration) |
否 | 電影長度 (請參閱 Duration)。例如 "7200s" 代表 2 小時。 |
content_ratings |
array of ContentRating |
否 | 官方內容分級 (請參閱 ContentRating)。 |
TvShowCandidate
TvShowCandidate 物件代表節目層級的電視節目。Google TV 和 Android TV 裝置會顯示節目資訊卡;請使用深層連結決定要在節目頁面或特定劇集開始播放。
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
title |
LocalizedString |
是 | 電視節目的標題 (請參閱 LocalizedString)。每個值為 1 到 100 個 Unicode 碼點,並會依傳送時的格式顯示。 |
description |
LocalizedString |
是 | 電視節目的簡短說明 (請參閱 LocalizedString)。每個值為 1 到 400 個 Unicode 碼點。 |
localized_media_images |
array of LocalizedMediaImage |
是 | 16:9 圖片,每種語言一個項目 (請參閱 LocalizedMediaImage)。至少須包含一張圖片。請提供最大可用來源,建議為 1920x1080 像素。 |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
是 | 每個平台和每種語言的深層連結 (請參閱 LocalizedProviderPlaybackUri)。至少一個項目必須列出 PLATFORM_ANDROID_TV。uri 可以指向節目頁面或特定一集。 |
first_episode_air_date |
Date |
是 | 第一集的播映日期 (請參閱 Date)。 |
external_entity_ids |
array of ExternalEntityId |
否 | 用於實體比對的外部目錄 ID (請參閱 ExternalEntityId)。每個 ID 類型最多只能有一個項目。 |
season_count |
integer (int32) |
否 | 貴服務提供的季數。 |
content_ratings |
array of ContentRating |
否 | 官方內容分級 (請參閱 ContentRating)。 |
LiveTvProgramCandidate
LiveTvProgramCandidate 物件代表排定的電視直播或串流活動。播送時間範圍是候選卡片的一部分,與父項候選卡片的 availability_intervals 分開,後者控制卡片可能顯示的時間。
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
title |
LocalizedString |
是 | 電視直播節目的標題 (請參閱 LocalizedString)。每個值為 1 到 100 個 Unicode 碼點,並會依傳送時的格式顯示。 |
description |
LocalizedString |
是 | 電視直播節目的簡短說明 (請參閱 LocalizedString)。每個值為 1 到 400 個 Unicode 碼點。 |
localized_media_images |
array of LocalizedMediaImage |
是 | 16:9 圖片,每種語言一個項目 (請參閱 LocalizedMediaImage)。至少須包含一張圖片。請提供最大可用來源,建議為 1920x1080 像素。 |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
是 | 每個平台和每種語言的深層連結 (請參閱 LocalizedProviderPlaybackUri)。至少一個項目必須列出 PLATFORM_ANDROID_TV。 |
broadcast_interval |
Interval |
是 | 節目播出的開始和結束時間 (請參閱 Interval)。start_time 和 end_time 均為必填。 |
external_entity_ids |
array of ExternalEntityId |
否 | 用於實體比對的外部目錄 ID (請參閱 ExternalEntityId)。每個 ID 類型最多只能有一個項目。 |
content_ratings |
array of ContentRating |
否 | 官方內容分級 (請參閱 ContentRating)。 |
支援的結構定義
候選酬載會參照下列共用物件,用於本地化文字、深層連結、圖片、外部 ID、推薦原因、顯示間隔、內容分級,以及常見的日期和時間類型。
LocalizedString
LocalizedString 物件會以一或多種語言顯示相同的文字。每個值都會標記語言,以便 Google TV 和 Android TV 裝置顯示與使用者電視裝置語言相符的文字:
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
values |
array of LocalizedText |
是 | 您提供的各語言文字 (請參閱 LocalizedText),至少須包含一個值。 |
LocalizedText
LocalizedText 物件是單一語言的文字:
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
text |
string |
是 | language_code 指定語言的文字。 |
language_code |
string |
是 | text 的 BCP-47 語言代碼,例如 "en-US" 或 "sr-Latn"。 |
LocalizedMediaImage
LocalizedMediaImage 物件會將圖片與圖片中任何文字的語言配對:
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
language_code |
string |
是 | 圖片中文字的 BCP-47 語言代碼,例如 "en-US" 或 "sr-Latn"。 |
image |
MediaImage |
是 | 16:9 圖片 (請參閱 MediaImage)。請提供最大可用來源,建議使用 1920x1080 像素。 |
LocalizedProviderPlaybackUri
LocalizedProviderPlaybackUri 物件會將深層連結與開啟內容的語言,以及開啟內容的應用程式配對:
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
playback_uri |
PlaybackUri |
是 | 深層連結和適用的平台 (請參閱 PlaybackUri)。 |
language_code |
string |
是 | 深層連結開啟內容的 BCP-47 語言代碼,例如 "en-US" 或 "sr-Latn"。 |
package_name |
string |
是 | 用於開啟深層連結的 Android 應用程式套件名稱 (例如 "com.example.tvapp")。 |
PlaybackUri
PlaybackUri 物件定義了深層連結及其目標平台:
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
uri |
string |
是 | 在應用程式中開始播放候選項目的深層連結 URI。 |
platforms |
array of string (enum) |
是 | 這個深層連結適用的平台。允許的值:PLATFORM_UNSPECIFIED、PLATFORM_ANDROID_TV、PLATFORM_ANDROID、PLATFORM_IOS。加入 Google TV 和 Android TV 裝置的 PLATFORM_ANDROID_TV。 |
MediaImage
MediaImage 物件會指定圖片網址、像素尺寸和無障礙文字:
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
url |
string |
是 | 可公開存取的圖片 HTTPS 網址。 |
width |
integer |
是 | 未修改 (最大) 圖片寬度 (以像素為單位)。 |
height |
integer |
是 | 未經修改的圖片高度 (最大值),以像素為單位。 |
accessibility_text |
string |
是 | 描述圖片的無障礙 (替代) 文字。 |
ExternalEntityId
ExternalEntityId 物件會將候選項目對應至外部目錄中的 ID。每個項目只能設定下列其中一個欄位,且候選人的 external_entity_ids 清單中,每種 ID 類型最多只能有一個項目:
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
tms_root_id |
string |
下列其中一項權限: | Gracenote TMS 根 ID。用於識別影視內容:電影、節目或劇集。 |
tms_id |
string |
下列其中一項權限: | Gracenote TMS 變化版本 ID。用於識別版本或播送清單。 |
data_feed_element_id |
string |
下列其中一項權限: | 媒體動作資料動態饋給中的實體 ID。這個值與資源名稱的 {recommendationsFeed} 區隔無關。 |
RecommendationContext
RecommendationContext 物件會說明推薦候選人的原因,以及該說明的適用時間長度:
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
recommendation_reason |
RecommendationReason |
否 | 推薦候選人的原因 (請參閱 RecommendationReason)。 |
validity_interval |
Interval |
否 | 這個情境適用的時間範圍 (請參閱 Interval)。舉例來說,候選項目只會在有限天數內視為新項目。如未設定,只要候選字詞仍儲存在系統中,情境就會持續套用。 |
RecommendationReason
RecommendationReason 物件會包含一個原因。請設定下列其中一個欄位:
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
top_on_partner |
object |
下列其中一項權限: | 候選項目是服務中排名最高的項目。包含單一正整數欄位 rank (例如 {"rank": 1} 代表「合作夥伴網頁頂端」)。 |
popular_on_partner |
object |
下列其中一項權限: | 候選項目在你的服務中很受歡迎。傳遞空白物件 ({})。 |
new_on_partner |
object |
下列其中一項權限: | 候選項目是服務中的新內容。傳遞空白物件 ({})。 |
generic |
object |
下列其中一項權限: | 自訂原因。包含單一 LocalizedString 欄位 generic_reason (請參閱 LocalizedString)。每個值為 1 到 100 個 Unicode 碼點。 |
ContentRating
ContentRating 物件代表分級機構指派的官方內容分級:
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
rating_system |
string |
是 | 分級機構或系統,例如 "MPAA"、"BBFC" 或 "CBFC"。 |
rating_value |
string |
是 | rating_system 定義的評分,例如 "PG-13" 或 "U/A 13+"。 |
Timestamp
Timestamp 在 JSON 中編碼為世界標準時間的 RFC 3339 字串,並加上 Z 後置字元,例如 "2026-10-01T18:00:00Z"。可使用小數秒數,例如 "2026-10-01T18:00:00.500Z"。
Duration
Duration 在 JSON 中編碼為字串,其中包含秒數,後接 s 後置字元,例如 "7200s" 代表 2 小時。允許使用秒數分數,例如 "5400.5s"。
Date
Date 是不含時區的日曆日期。在 JSON 中,這項資訊會編碼為具有下列欄位的物件:
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
year |
integer |
是 | 日期的年份,例如 2025。 |
month |
integer |
否 | 一年中的月份,從 1 到 12。設為 0,或在月份不明時省略。 |
day |
integer |
否 | 當月日期,從 1 到 31,且在指定年月內有效。設為 0,或在日期不明時省略。需要 month。 |
舉例來說,{"year": 2025, "month": 1, "day": 17} 代表 2025 年 1 月 17 日,{"year": 2025, "month": 1} 代表 2025 年 1 月,但日期不明,{"year": 2025} 則代表 2025 年的某個日期,但月份和日期不明。
Interval
Interval 是半開放時間範圍,從 start_time (含) 開始,到 end_time (不含) 結束。當 start_time <= T 和 T < end_time 時,時間 T 位於間隔內。
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
start_time |
string (Timestamp) |
是 | 時間範圍的開始時間 (含) (請參閱 Timestamp),例如 "2026-10-01T18:00:00Z"。 |
end_time |
string (Timestamp) |
是 | 時間範圍的結束時間 (不含,請參閱 Timestamp),例如 "2026-10-01T21:00:00Z"。必須晚於 start_time。 |
要求範例
以下範例會將合作夥伴 example-partner 的動態饋給 in-en-cricket 候選項目,替換為三個候選項目 (電影、電視節目和電視直播節目)。電影中的文字有兩種語言:
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"
}
]
}
]
}'
回應和替換行為
本節說明 replaceCandidates 傳回的 HTTP 回應,以及每次呼叫如何更新儲存的候選項目。
ReplaceCandidatesResponse
如果要求成功,API 會傳回 HTTP 200 OK 和 ReplaceCandidatesResponse 主體:
| 欄位 | 類型 | 說明 |
|---|---|---|
replaced_candidates_count |
integer (int32) |
已更換的候選項目數量。 |
針對上述範例要求,回應如下:
{
"replaced_candidates_count": 3
}
替換行為
設計整合時,請務必瞭解 replaceCandidates 如何更新儲存的候選字詞:
- 完整取代各個動態饋給。每次呼叫都會完全取代先前儲存的候選清單,用於網址路徑中指定的動態饋給。請務必傳送該動態饋給的完整有效候選項目。
- 其他動態饋給維持不變。如果未將候選項目傳送至動態饋給,動態饋給會維持不變,直到您傳送為止。舉例來說,替換某個動態饋給的候選項目,不會修改任何其他動態饋給儲存的候選項目,而替換
{recommendationsFeed}-staging的候選項目也不會修改{recommendationsFeed}。 - 每個動態饋給呼叫一次。如要更新多個動態饋給,請為每個動態饋給發出一個呼叫。這些呼叫彼此獨立:如果其中一個呼叫失敗,其他動態饋給會保留新的候選項目,您只需重試失敗的呼叫。
- 至少每 30 天重新提交一次有效的動態饋給。即使動態饋給的目錄未變更,也請至少每 30 天重新傳送一次每個有效動態饋給 (或每天/每週定期傳送,並隨機調整時間),確保候選項目保持有效狀態且不會過期。將
availability_intervalsend_time設在遙遠的未來,並不會取代定期重新傳送。 - 不可分割執行。API 會以不可分割的方式套用要求。如果任何候選項目未通過驗證,API 會拒絕整個要求,且動態饋給會保留先前的候選項目。