Google TV Video Discovery REST API מאפשר לשותפים לשלוח המלצות לא מותאמות אישית למכשירי Google TV ו-Android TV משרתי הקצה העורפי שלהם. שליחת המועמדים מהקצה העורפי של השותף מאפשרת לשמור על עדכניות הקטלוג וההמלצות לתוכניות בשידור חי במכשירים האלה, בלי שהמשתמשים יצטרכו לפתוח את האפליקציה של השותף.
השותפים שולחים מועמדים לפידים של המלצות. Google יוצרת כל פיד בשביל השותף ומגדירה את המדינות או האזורים ואת השפות של מכשירי הטלוויזיה שבהם הפיד יוצג. פיד יכול להכיל סרטים, תוכניות טלוויזיה ותוכניות טלוויזיה בשידור חי.
אם אתם רוצים לפרסם המלצות בהתאמה אישית מהמכשיר של המשתמש, עיינו במאמר שילוב המלצות במכשיר באמצעות Engage SDK.
דרישות מוקדמות
לפני שאתם משלבים את ה-API בארכיטקטורת REST, ודאו שיש לכם את הדברים הבאים:
- פרויקט ב-Google Cloud שממנו אפשר לשלוח בקשות API.
- חשבון Google Workspace שמשויך לארגון שלכם.
- מזהה השותף ומזהי פיד ההמלצות, שסופקו על ידי נציג השותף של Google TV במהלך תהליך ההצטרפות. במאמר פידים של המלצות מוסבר איך משתמשים במזהים האלה.
לקבלת גישה
הגישה ל-Google TV Video Discovery API בארכיטקטורת REST מוגבלת לשותפי מדיה רשומים של Google TV. כל מתקשר מאומת באמצעות חשבון שירות ב-Google Cloud, שממופה בשרת למזהה שותף אחד בדיוק.
כדי לבקש ולהגדיר גישה ל-API, פועלים לפי השלבים הבאים:
- יצירת חשבון Google Workspace כדי להגדיר חשבון לארגון, פועלים לפי ההוראות בדף התמיכה של Google Workspace.
- איתור מספר הלקוח ב-Google Workspace כדי למצוא את מספר הלקוח (לדוגמה,
C0123abcd), פועלים לפי השלבים שמפורטים במאמר איפה מוצאים את מספר הלקוח. - יוצרים פרויקט וחשבון שירות ב-Google Cloud. במסוף Google Cloud, בארגון שלכם ב-Google Workspace, יוצרים פרויקט ב-Google Cloud וחשבון שירות לשרת בק-אנד.
- בקשה להצטרפות של שותף. ספקו לנציג שותף Google TV שלכם את מספר הלקוח של Google Workspace, את מספר הפרויקט של Google Cloud ואת כתובת הדוא"ל של חשבון השירות (או מספר מספרי ייחודי), יחד עם המדינות או האזורים ושפות מכשירי הטלוויזיה שאליהם תרצו לשלוח מועמדים. נציג השותף של Google TV יודיע לכם אחרי מיפוי הארגון, הפרויקט וחשבון השירות של Google Workspace למזהה השותף שלכם, וייתן לכם את מזהי פיד ההמלצות שנוצרו בשביל השותף.
- מפעילים את ה-API ויוצרים פרטי כניסה. אחרי שהנציג מאשר שקיבלתם גישה, אתם צריכים להפעיל את Google TV Video Discovery API (
tvvideodiscovery.googleapis.com) בפרויקט בענן שלכם ב-Google Cloud וליצור פרטי כניסה ל-OAuth 2.0 בשביל חשבון השירות. אימות הבקשות. מבקשים טוקני גישה מסוג OAuth 2.0 באמצעות היקף ההרשאות הבא של OAuth, ומעבירים את הטוקן בכותרת ה-HTTP של
Authorization: Bearerבכל קריאה:https://www.googleapis.com/auth/tvvideodiscovery
מגבלות קצב
בקשות אל replaceCandidates כפופות למגבלות הקצב הבאות לכל פרויקט ולמגבלות המטען הייעודי (payload) לכל בקשה:
| הגבלה | ערך |
|---|---|
| בקשות לדקה לכל פרויקט בענן של Google | 5 |
| בקשות ביום לכל פרויקט בענן של Google | 100 |
RecommendationCandidate פריטים לכל בקשה |
1 עד 25 |
בקשות לפיד ה-staging נספרות באותה מכסה כמו בקשות לפיד ה-production התואם.
פידים של המלצות
ה-API מארגן את ההמלצות האפשריות בפידים של המלצות. פיד מזוהה לפי שם משאב בפורמט הבא:
partners/{partner}/recommendationsFeeds/{recommendationsFeed}
שותפים
{partner} הוא מזהה השותף ש-Google מקצה לכם במהלך ההצטרפות. חשבון השירות שבאמצעותו אתם מבצעים אימות ממופה למזהה שותף אחד בלבד.
בקשות שכוללות שם של שותף אחר נכשלות עם השגיאה 403 PERMISSION_DENIED.
מזהי פידים
{recommendationsFeed} הוא מזהה הפיד ש-Google יוצרת בשבילכם במהלך תהליך ההצטרפות. אי אפשר ליצור פידים באמצעות ה-API.
כל פיד מטרגט קהל ש-Google מגדירה כשהיא יוצרת את הפיד:
- מדינות או אזורים: המקומות שבהם מוצגים הפריטים מהפיד.
- שפות במכשירי טלוויזיה: השפות שהמשתמשים המטורגטים הגדירו במכשירי הטלוויזיה שלהם. זו לא השפה של הטקסט שאתם שולחים. כדי לספק טקסט ביותר משפה אחת, עיינו במאמר
LocalizedString.
Google מחליטה איפה המועמדים של הפיד יופיעו במכשירי Google TV ו-Android TV. הדרך לשלוח מועמדים לכל פיד היא זהה.
פידים בסביבת Staging
לכל פיד יש פיד תואם בסביבת Staging בשם {recommendationsFeed}-staging. פיד Staging מוצג רק לחשבונות בדיקה ברשימת היתרים. השתמשו בו כדי לאמת את השילוב לפני שאתם שולחים מועמדים לפיד מוצרים בסביבת הייצור.
פידים של Staging משתמשים באותם נקודת קצה, פרטי כניסה, אימות בקשות ומכסה כמו פידים של סביבת הייצור. רק הקהל שונה.
החלפה
הפיד הוא יחידת ההחלפה. כל קריאה ל-replaceCandidates מחליפה את כל המועמדים שאוחסנו בעבר בפיד הזה, ולא משפיעה על אף פיד אחר.
החלפת המלצות פוטנציאליות
משתמשים ב-method partners.recommendationsFeeds.replaceCandidates כדי לשלוח את הרשימה המלאה של המועמדים להמלצה בפיד אחד.
בקשת HTTP
POST https://tvvideodiscovery.googleapis.com/v1/{name=partners/*/recommendationsFeeds/*}:replaceCandidates
נתיב כתובת ה-URL מכיל את שם המשאב של הפיד שהמועמדים שלו מוחלפים. גוף הבקשה מכיל את כל השדות שלא נכללים בנתיב כתובת ה-URL.
פרמטרים של הנתיב
| פרמטר | תיאור |
|---|---|
name |
חובה. שם המשאב של הפיד, בפורמט partners/{partner}/recommendationsFeeds/{recommendationsFeed}. הערך של {partner} חייב להיות מזהה השותף שאליו ממופה חשבון השירות שלכם. {recommendationsFeed} חייב להיות מזהה פיד ש-Google יצרה בשביל השותף הזה, או מזהה הפיד הזה עם הסיומת -staging. |
ReplaceCandidatesRequest
גוף הבקשה ב-JSON בנוי באופן הבא:
| שדה | סוג | חובה | תיאור |
|---|---|---|---|
recommendation_candidates |
array of RecommendationCandidate |
כן | רשימה של 1 עד 25 פריטי RecommendationCandidate. המועמדים האלה מחליפים את המועמדים הנוכחיים בפיד. |
סכימות מועמדות
כל פריט ב-recommendation_candidates הוא אובייקט RecommendationCandidate שמכיל מטען ייעודי (payload) אחד מסוג מועמד, סיבות אופציונליות להמלצה וחלונות אופציונליים של חלון זמינות לתצוגה.
RecommendationCandidate
אובייקט RecommendationCandidate מכיל בדיוק שדה אחד של מטען ייעודי (payload) מסוג מדיה, סיבות אופציונליות להמלצה ומרווחי זמינות אופציונליים.
שדה איחוד candidate_type
חובה להגדיר את candidate_type: צריך להגדיר בדיוק אחד מהשדות הבאים. השדות האלה לא יכולים להופיע ביחד, ומועמד שלא מגדיר אף אחד מהם או מגדיר יותר מאחד מהם נדחה. אין מפתח candidate_type ב-JSON. צריך להגדיר את השדה שנבחר ישירות באובייקט RecommendationCandidate.
| שדה | סוג | תיאור |
|---|---|---|
movie_candidate |
MovieCandidate |
סרט VOD (ראו 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 מייצג סרט VOD:
| שדה | סוג | חובה | תיאור |
|---|---|---|---|
title |
LocalizedString |
כן | שם הסרט (ראו LocalizedString). כל ערך הוא בין 1 ל-100 מיקומי תווים (code points) של Unicode ומוצג כפי שנשלח. |
description |
LocalizedString |
כן | תיאור קצר של הסרט (ראו LocalizedString). כל ערך הוא 1 עד 400 מיקומי תווים (code points) של Unicode. |
localized_media_images |
array of LocalizedMediaImage |
כן | תמונות של גרפיקה ביחס גובה-רוחב של 16:9, רשומה אחת לכל שפה (ראו LocalizedMediaImage). חייבת להיות לפחות תמונה אחת. צריך לספק את המקור הגדול ביותר שזמין. מומלץ להשתמש ב-1,920x1,080 פיקסלים. |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
כן | קישורי עומק לכל פלטפורמה ולכל שפה (ראו LocalizedProviderPlaybackUri). לפחות רשומה אחת צריכה לכלול את PLATFORM_ANDROID_TV. |
release_date |
Date |
כן | תאריך ההפצה של הסרט (ראו Date). |
external_entity_ids |
array of ExternalEntityId |
לא | מזהי קטלוג חיצוניים להתאמת ישויות (ראו ExternalEntityId). לכל היותר רשומה אחת לכל סוג מזהה. |
duration |
string (Duration) |
לא | משך הסרט (ראו Duration). לדוגמה, "7200s" למשך שעתיים. |
content_ratings |
array of ContentRating |
לא | סיווגי תוכן רשמיים (ראו ContentRating). |
TvShowCandidate
האובייקט TvShowCandidate מייצג תוכנית טלוויזיה ברמת התוכנית. במכשירי Google TV ו-Android TV מוצג כרטיס של התוכנית. אתם יכולים להשתמש בקישור העומק כדי להחליט אם ההפעלה תתחיל בדף התוכנית או בפרק ספציפי.
| שדה | סוג | חובה | תיאור |
|---|---|---|---|
title |
LocalizedString |
כן | שם תוכנית הטלוויזיה (ראו LocalizedString). כל ערך מורכב מ-1 עד 100 מיקומי תווים (code points) ב-Unicode ומוצג כפי שנשלח. |
description |
LocalizedString |
כן | תיאור קצר של תוכנית הטלוויזיה (ראו LocalizedString). כל ערך הוא 1 עד 400 מיקומי תווים (code points) של Unicode. |
localized_media_images |
array of LocalizedMediaImage |
כן | תמונות של גרפיקה ביחס גובה-רוחב של 16:9, רשומה אחת לכל שפה (ראו LocalizedMediaImage). חייבת להיות לפחות תמונה אחת. צריך לספק את המקור הגדול ביותר שזמין. מומלץ להשתמש ב-1,920x1,080 פיקסלים. |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
כן | קישורי עומק לכל פלטפורמה ולכל שפה (ראו LocalizedProviderPlaybackUri). לפחות רשומה אחת צריכה לכלול את PLATFORM_ANDROID_TV. ה-uri יכול להפנות לדף התוכנית או לפרק. |
first_episode_air_date |
Date |
כן | תאריך הקרנת הבכורה של הפרק הראשון (ראו Date). |
external_entity_ids |
array of ExternalEntityId |
לא | מזהי קטלוג חיצוניים להתאמת ישויות (ראו ExternalEntityId). לכל היותר רשומה אחת לכל סוג מזהה. |
season_count |
integer (int32) |
לא | מספר העונות שזמינות בשירות שלכם. |
content_ratings |
array of ContentRating |
לא | סיווגי תוכן רשמיים (ראו ContentRating). |
LiveTvProgramCandidate
האובייקט LiveTvProgramCandidate מייצג שידור טלוויזיה בשידור חי או אירוע בסטרימינג שנקבעו מראש. חלון השידור הוא חלק מהמועמד, והוא נפרד מהשדות availability_intervals של המועמד הראשי, שקובעים מתי אפשר להציג את הכרטיס.
| שדה | סוג | חובה | תיאור |
|---|---|---|---|
title |
LocalizedString |
כן | שם התוכנית בטלוויזיה בשידור חי (ראו LocalizedString). כל ערך מורכב מ-1 עד 100 מיקומי תווים (code points) ב-Unicode ומוצג כמו שנשלח. |
description |
LocalizedString |
כן | תיאור קצר של התוכנית בטלוויזיה בשידור חי (ראו LocalizedString). כל ערך הוא בין 1 ל-400 מיקומי תווים (code points) של Unicode. |
localized_media_images |
array of LocalizedMediaImage |
כן | תמונות של גרפיקה ביחס גובה-רוחב של 16:9, רשומה אחת לכל שפה (ראו LocalizedMediaImage). חייבת להיות לפחות תמונה אחת. צריך לספק את המקור הגדול ביותר שזמין. מומלץ להשתמש ב-1,920x1,080 פיקסלים. |
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 |
לא | מזהי קטלוג חיצוניים להתאמת ישויות (ראו ExternalEntityId). לכל היותר רשומה אחת לכל סוג מזהה. |
content_ratings |
array of ContentRating |
לא | סיווגי תוכן רשמיים (ראו ContentRating). |
סכימות נתמכות
האובייקטים של המועמדים מפנים לאובייקטים המשותפים הבאים: טקסט מקומי, קישורי עומק, גרפיקה, מזהים חיצוניים, סיבות להמלצה, מרווחי זמן להצגה, סיווגי תוכן וסוגים מוכרים של תאריך ושעה.
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). צריך לספק את המקור הגדול ביותר שזמין. מומלץ להשתמש בתמונה בגודל 1,920x1,080 פיקסלים. |
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. כולל PLATFORM_ANDROID_TV למכשירי Google TV ו-Android TV. |
MediaImage
האובייקט MediaImage מציין את כתובת ה-URL של התמונה, את המידות שלה בפיקסלים ואת טקסט הנגישות:
| שדה | סוג | חובה | תיאור |
|---|---|---|---|
url |
string |
כן | כתובת URL מסוג HTTPS של התמונה, שנגישה לכולם. |
width |
integer |
כן | רוחב התמונה המקורי (המקסימלי) בפיקסלים. |
height |
integer |
כן | גובה התמונה המקורי (המקסימלי) בפיקסלים. |
accessibility_text |
string |
כן | טקסט נגישות (חלופי) שמתאר את התמונה. |
ExternalEntityId
האובייקט ExternalEntityId ממפה מועמד למזהה בקטלוג חיצוני. צריך להגדיר בדיוק אחד מהשדות הבאים לכל רשומה, ולכלול לכל היותר רשומה אחת לכל סוג מזהה ברשימת external_entity_ids של המועמד:
| שדה | סוג | חובה | תיאור |
|---|---|---|---|
tms_root_id |
string |
אחת | מזהה הבסיס של Gracenote TMS. מזהה כותר: סרט, תוכנית או פרק. |
tms_id |
string |
אחת | מזהה וריאנט של Gracenote TMS. מזהה מהדורה או רשימת שידורים. |
data_feed_element_id |
string |
אחת | מזהה הישות מפיד הנתונים של Media Actions. הערך הזה לא קשור לקטע {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 מיקומי תווים (code points) של Unicode. |
ContentRating
האובייקט ContentRating מייצג סיווג תוכן רשמי שהוקצה על ידי סוכנות דירוג:
| שדה | סוג | חובה | תיאור |
|---|---|---|---|
rating_system |
string |
כן | סוכנות או מערכת דירוג, לדוגמה "MPAA", "BBFC" או "CBFC". |
rating_value |
string |
כן | סיווג כפי שהוגדר על ידי rating_system, לדוגמה "PG-13" או "U/A 13+". |
Timestamp
Timestamp מקודד ב-JSON כמחרוזת RFC 3339 ב-UTC עם הסיומת Z, לדוגמה "2026-10-01T18:00:00Z". אפשר להשתמש בשניות חלקיות, לדוגמה "2026-10-01T18:00:00.500Z".
Duration
Duration מקודד ב-JSON כמחרוזת שמכילה את מספר השניות ואחריו הסיומת s, לדוגמה "7200s" לשעתיים. אפשר להשתמש בשניות חלקיות, לדוגמה "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} מייצג את 17 בינואר 2025, {"year": 2025, "month": 1} מייצג את ינואר 2025 עם יום לא ידוע, ו-{"year": 2025} מייצג תאריך בשנת 2025 עם חודש ויום לא ידועים.
Interval
Interval הוא חלון זמן חצי פתוח שמתחיל ב-start_time (כולל) ומסתיים ב-end_time (לא כולל). השעה T נמצאת בטווח אם start_time <= T וגם T < end_time.
| שדה | סוג | חובה | תיאור |
|---|---|---|---|
start_time |
string (Timestamp) |
כן | ההתחלה של חלון הזמן (כולל, ראו Timestamp), לדוגמה "2026-10-01T18:00:00Z". |
end_time |
string (Timestamp) |
כן | סיום חלון הזמן (לא כולל, ראו Timestamp), לדוגמה "2026-10-01T21:00:00Z". התאריך חייב להיות אחרי start_time. |
דוגמה לבקשה
בדוגמה הבאה, המועמדים של פיד in-en-cricket של השותף example-partner מוחלפים בשלושה מועמדים (סרט, תוכנית טלוויזיה ותוכנית טלוויזיה בשידור חי). הטקסט בסרט מופיע בשתי שפות:
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"
}
]
}
]
}'
התגובה וההתנהגות של ההחלפה
בקטע הזה מתוארת תגובת ה-HTTP שמוחזרת על ידי replaceCandidates ואיך כל קריאה מעדכנת את המועמדים ששמרתם.
ReplaceCandidatesResponse
אם הבקשה תתבצע בהצלחה, ה-API יחזיר את קוד הסטטוס 200 OK של HTTP עם גוף ReplaceCandidatesResponse:
| שדה | סוג | תיאור |
|---|---|---|
replaced_candidates_count |
integer (int32) |
מספר המועמדים שהוחלפו. |
לבקשה לדוגמה הקודמת, התשובה היא:
{
"replaced_candidates_count": 3
}
התנהגות ההחלפה
כדי לתכנן את השילוב, חשוב להבין איך replaceCandidates מעדכן את המועמדים השמורים:
- החלפה מלאה של כל פיד. כל קריאה מחליפה לחלוטין את רשימת המועמדים שנשמרה קודם לכן בפיד שצוין בנתיב כתובת ה-URL. תמיד צריך לשלוח את הקבוצה המלאה של המועמדים הפעילים בפיד הזה.
- פידים אחרים לא ישתנו. פידים שלא תשלחו אליהם מועמדים לא ישתנו עד שתעשו את זה. לדוגמה, החלפת המועמדים של פיד אחד לא משנה את המועמדים ששמורים בפיד אחר, והחלפת המועמדים של
{recommendationsFeed}-stagingלא משנה את{recommendationsFeed}. - קריאה אחת לכל פיד. כדי לעדכן כמה פידים, צריך לבצע קריאה אחת לכל פיד. הקריאות לא תלויות זו בזו: אם אחת מהן נכשלת, הפידים האחרים שומרים על המועמדים החדשים שלהם, ואתם מנסים שוב רק את הקריאה שנכשלה.
- שולחים מחדש פידים פעילים לפחות כל 30 יום. גם אם הקטלוג של הפיד לא השתנה, צריך לשלוח מחדש כל פיד פעיל לפחות פעם אחת ב-30 יום (או לפי לוח זמנים קבוע, יומי או שבועי, עם ריצוד אקראי) כדי שהמועמדים יישארו פעילים ולא יפוג תוקפם. הגדרה של
availability_intervalsend_timeלמועד רחוק בעתיד לא מחליפה את השליחה מחדש מדי פעם. - הרצה אטומית. ה-API מחיל את הבקשה באופן אטומי. אם אחד מהמועמדים נכשל באימות, ה-API דוחה את כל הבקשה והפיד שומר על המועמדים הקודמים שלו.