שילוב המלצות באמצעות API בארכיטקטורת REST

‫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, פועלים לפי השלבים הבאים:

  1. יצירת חשבון Google Workspace כדי להגדיר חשבון לארגון, פועלים לפי ההוראות בדף התמיכה של Google Workspace.
  2. איתור מספר הלקוח ב-Google Workspace כדי למצוא את מספר הלקוח (לדוגמה, C0123abcd), פועלים לפי השלבים שמפורטים במאמר איפה מוצאים את מספר הלקוח.
  3. יוצרים פרויקט וחשבון שירות ב-Google Cloud. במסוף Google Cloud, בארגון שלכם ב-Google Workspace, יוצרים פרויקט ב-Google Cloud וחשבון שירות לשרת בק-אנד.
  4. בקשה להצטרפות של שותף. ספקו לנציג שותף Google TV שלכם את מספר הלקוח של Google Workspace, את מספר הפרויקט של Google Cloud ואת כתובת הדוא"ל של חשבון השירות (או מספר מספרי ייחודי), יחד עם המדינות או האזורים ושפות מכשירי הטלוויזיה שאליהם תרצו לשלוח מועמדים. נציג השותף של Google TV יודיע לכם אחרי מיפוי הארגון, הפרויקט וחשבון השירות של Google Workspace למזהה השותף שלכם, וייתן לכם את מזהי פיד ההמלצות שנוצרו בשביל השותף.
  5. מפעילים את ה-API ויוצרים פרטי כניסה. אחרי שהנציג מאשר שקיבלתם גישה, אתם צריכים להפעיל את Google TV Video Discovery API‏ (tvvideodiscovery.googleapis.com) בפרויקט בענן שלכם ב-Google Cloud וליצור פרטי כניסה ל-OAuth 2.0 בשביל חשבון השירות.
  6. אימות הבקשות. מבקשים טוקני גישה מסוג 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_intervals end_time למועד רחוק בעתיד לא מחליפה את השליחה מחדש מדי פעם.
  • הרצה אטומית. ה-API מחיל את הבקשה באופן אטומי. אם אחד מהמועמדים נכשל באימות, ה-API דוחה את כל הבקשה והפיד שומר על המועמדים הקודמים שלו.