Google TV Video Discovery REST API به شرکا اجازه میدهد نامزدهای توصیهشده غیرشخصیسازیشده را از سرورهای زیرینه خود به دستگاههای Google TV و Android TV ارسال کنند. ارسال نامزدها از باطن آنها باعث میشود کاتالوگ شریک و توصیههای برنامهسازی زنده در این دستگاهها بدون نیاز به باز کردن برنامه شریک توسط کاربران، تازه بماند.
شرکا نامزدها را به فیدهای توصیهها ارسال میکنند. Google هر فید را برای شریک ایجاد میکند و کشورها یا مناطق و زبانهای دستگاه تلویزیون را که فید به آنها نشان داده میشود پیکربندی میکند. فید میتواند حاوی فیلم، نمایش تلویزیونی، و برنامههای تلویزیونی زنده باشد.
اگر میخواهید توصیههای شخصیسازیشده را از دستگاه کاربر منتشر کنید، ادغام توصیهها در دستگاه بااستفاده از Engage SDK را ببینید.
پیشنیازها
قبلاز ادغام با REST API، مطمئن شوید که موارد زیر را دارید:
- پروژه Google Cloud برای ارسال درخواستهای API.
- حساب Google Workspace مرتبط با سازمانتان.
- شناسه شریک و شناسههای فید توصیهها که نماینده شریک Google TV درطول آمادهسازی ارائه کرده است. برای اطلاع از نحوه استفاده از این شناسهها، فیدهای توصیهها را ببینید.
دسترسی یافتن
دسترسی به Google TV Video Discovery REST API به شرکای رسانهای ثبتشده Google TV محدود شده است. هر تماسگیرنده بااستفاده از حساب سرویس Google Cloud که در سرور دقیقاً به یک شناسه شریک نگاشت شده است اصالتسنجی میشود.
برای درخواست و پیکربندی دسترسی به API، این مراحل را دنبال کنید:
- ایجاد کردن حساب Google Workspace. دستورالعملهای موجود در صفحه پشتیبانی Google Workspace را برای راهاندازی حساب برای سازمانتان دنبال کنید.
- «شناسه مشتری» Google Workspace خود را پیدا کنید. با دنبال کردن مراحل موجود در
پیدا کردن شناسه مشتری، «شناسه مشتری» خود را (برای
مثال،
C0123abcd) پیدا کنید. - پروژه Google Cloud و حساب خدمات ایجاد کنید. در Google Cloud Console در سازمان Google Workspace، پروژه Google Cloud و حساب سرویس برای سرور زیرینه خود ایجاد کنید.
- درخواست آمادهسازی شریک. شناسه مشتری Google Workspace، شناسه پروژه Google Cloud، و نشانی ایمیل حساب سرویس (یا شناسه عددی یکتا) خود را بههمراه کشورها یا مناطق و زبانهای دستگاه تلویزیونی که میخواهید نامزدها را به آنها ارسال کنید، به نماینده شریک Google TV خود ارائه دهید. نماینده شریک Google TV شما پساز نگاشت سازمان، پروژه، و حساب سرویس Google Workspace شما به شناسه شریکتان، به شما اطلاع میدهد و شناسههای فید توصیههای ایجادشده برای شریکتان را به شما میدهد.
- میانای برنامهسازی کاربردی را فعال کنید و اطلاعات کاربری تولید کنید. پساز اینکه نمایندهتان
تأیید کرد دسترسی اعطا شده است، Google TV Video Discovery API
(
tvvideodiscovery.googleapis.com) را در پروژه Google Cloud خود فعال کنید و اعتبارنامه OAuth 2.0 را برای حساب سرویس خود تولید کنید. درخواستهایتان را اصالتسنجی کنید. درخواست کدهای دسترسی OAuth 2.0 بااستفاده از دامنه OAuth زیر و ارسال کد در سرایند
Authorization: BearerHTTP در هر تماس:https://www.googleapis.com/auth/tvvideodiscovery
حد نرخ
درخواستهای ارسالشده به replaceCandidates مشمول محدودیتهای نرخ بهازای پروژه و سقفهای بار مفید بهازای درخواست زیر است:
| حد | مقدار |
|---|---|
| درخواستها در دقیقه برای هر پروژه Google Cloud | 5 |
| درخواستها در روز برای هر پروژه Google Cloud | ۱۰۰ |
RecommendationCandidate مورد در هر درخواست |
۱ تا ۲۵ |
درخواستهای ارسالشده به فید آمادهسازی در همان سهمیه درخواستهای ارسالشده به فید تولید مربوطه محاسبه میشود.
فیدهای توصیهها
API نامزدهای توصیه را در فیدهای توصیهها سازماندهی میکند. فید با نام منبعی با قالب زیر شناسایی میشود:
partners/{partner}/recommendationsFeeds/{recommendationsFeed}
شرکا
{partner} شناسه شریکی است که Google درطول آمادهسازی به شما اختصاص میدهد. حساب
خدماتی که با آن اصالتسنجی میکنید دقیقاً به یک شناسه شریک نگاشت شده باشد.
درخواستهایی که نام شریک دیگری را ذکر میکنند با 403 PERMISSION_DENIED ناموفق میشوند.
شناسههای فید
{recommendationsFeed} شناسه فیدی است که Google درطول آمادهسازی برای شما ایجاد میکند. نمیتوانید با میانای برنامهسازی کاربردی فید ایجاد کنید.
هر فید مخاطبی را هدف قرار میدهد که 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} باید شناسه شریکی باشد که حساب سرویس شما به آن نگاشت شده است. {recommendationsFeed} باید شناسه فیدی باشد که Google برای آن شریک ایجاد کرده است، یا شناسه فیدی باشد که پسوند -staging دارد. |
ReplaceCandidatesRequest
متن درخواست JSON ساختار زیر را دارد:
| فیلد | نوع | الزامی | شرح |
|---|---|---|---|
recommendation_candidates |
array of RecommendationCandidate |
بله | فهرستی از ۱ تا ۲۵ مورد RecommendationCandidate. این نامزدها جایگزین نامزدهای فعلی فید میشوند. |
طرحوارههای نامزد
هر مورد در recommendation_candidates یک شیء RecommendationCandidate است
که حاوی یک بار داده از نوع نامزد، دلایل توصیه اختیاری، و
پنجرههای دسترسپذیری نمایش اختیاری است.
RecommendationCandidate
شیء RecommendationCandidate دقیقاً شامل یک فیلد محموله نوع رسانه، دلایل توصیه اختیاری، و فاصلههای زمانی دردسترس بودن اختیاری است.
فیلد اتحادیه candidate_type
candidate_type الزامی است: دقیقاً یکی از فیلدهای زیر را تنظیم کنید. فیلدها بهصورت متقابل انحصاریاند و نامزدی که هیچکدام یا بیشاز یکی را تنظیم کند رد میشود. کلید candidate_type در JSON وجود ندارد؛ فیلد انتخابشده را مستقیماً روی شیء 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 را ببینید). هر مقدار ۱ تا ۱۰۰ نقطه کد یونیکد است و همانطور که ارسال شده نشان داده میشود. |
description |
LocalizedString |
بله | شرح کوتاه فیلم (LocalizedString را ببینید). هر مقدار ۱ تا ۴۰۰ نقطه کد یونیکد است. |
localized_media_images |
array of LocalizedMediaImage |
بله | تصاویر کار هنری ۱۶:۹، یک ورودی برای هر زبان (LocalizedMediaImage را ببینید). باید حداقل یک تصویر داشته باشد. بزرگترین منبع موجود را ارائه دهید؛ ۱۰۸۰×۱۹۲۰ پیکسل توصیه میشود. |
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 را ببینید). هر مقدار ۱ تا ۱۰۰ نقطه کد یونیکد است و همانطور که ارسال شده است نشان داده میشود. |
description |
LocalizedString |
بله | توضیح کوتاه نمایش تلویزیونی (LocalizedString را ببینید). هر مقدار ۱ تا ۴۰۰ نقطه کد یونیکد است. |
localized_media_images |
array of LocalizedMediaImage |
بله | تصاویر کار هنری ۱۶:۹، یک ورودی برای هر زبان (LocalizedMediaImage را ببینید). باید حداقل یک تصویر داشته باشد. بزرگترین منبع موجود را ارائه دهید؛ ۱۰۸۰×۱۹۲۰ پیکسل توصیه میشود. |
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 را ببینید). هر مقدار ۱ تا ۱۰۰ نقطه کد یونیکد است و همانطور که ارسال شده است نشان داده میشود. |
description |
LocalizedString |
بله | شرح کوتاهی از برنامه تلویزیونی زنده (LocalizedString را ببینید). هر مقدار ۱ تا ۴۰۰ نقطه کد یونیکد است. |
localized_media_images |
array of LocalizedMediaImage |
بله | تصاویر کار هنری ۱۶:۹، یک ورودی برای هر زبان (LocalizedMediaImage را ببینید). باید حداقل یک تصویر داشته باشد. بزرگترین منبع موجود را ارائه دهید؛ ۱۰۸۰×۱۹۲۰ پیکسل توصیه میشود. |
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 |
بله | کد زبان BCP-47 برای text، مثل "en-US" یا "sr-Latn". |
LocalizedMediaImage
شیء LocalizedMediaImage تصویر را با زبان هر نوشتاری در تصویر جفت میکند:
| فیلد | نوع | الزامی | شرح |
|---|---|---|---|
language_code |
string |
بله | کد زبان BCP-47 نوشتار موجود در تصویر، مثل "en-US" یا "sr-Latn". |
image |
MediaImage |
بله | تصویر ۱۶:۹ (MediaImage را ببینید). بزرگترین منبع دردسترس را ارائه دهید؛ ۱۹۲۰x۱۰۸۰ پیکسل توصیه میشود. |
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 |
بله | شناسه منبع یکسان پیوند عمیق که بازپخش نامزد را در برنامهتان شروع میکند. |
platforms |
array of string (enum) |
بله | پلاتفرمهایی که این پیوند عمیق برای آنها اعمال میشود. مقادیر مجاز: PLATFORM_UNSPECIFIED، PLATFORM_ANDROID_TV، PLATFORM_ANDROID، PLATFORM_IOS. شامل PLATFORM_ANDROID_TV برای دستگاههای Google TV و Android TV. |
MediaImage
شیء MediaImage نشانی وب تصویر، ابعاد پیکسل آن، و
نوشتار دسترسپذیری را مشخص میکند:
| فیلد | نوع | الزامی | شرح |
|---|---|---|---|
url |
string |
بله | نشانی وب 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 |
یکی از | شناسه نهاد از فید داده «کنشهای رسانه» شما. این مقدار به بخش {recommendationsFeed} نام منبع مربوط نیست. |
RecommendationContext
شیء RecommendationContext توضیح میدهد که چرا نامزد توصیه شده است و
این توضیح تا چه مدت اعمال میشود:
| فیلد | نوع | الزامی | شرح |
|---|---|---|---|
recommendation_reason |
RecommendationReason |
نه | دلیل توصیه شدن نامزد (RecommendationReason را ببینید). |
validity_interval |
Interval |
نه | پنجره زمانی که این بافت در آن اعمال میشود (Interval را ببینید). برای مثال، یک نامزد فقط برای تعداد محدودی روز جدید است. اگر تنظیم نشده باشد، بافت تا زمانی که نامزد ذخیره شده باشد اعمال میشود. |
RecommendationReason
شیء RecommendationReason یک دلیل دارد. دقیقاً یکی از فیلدهای زیر را تنظیم کنید:
| فیلد | نوع | الزامی | شرح |
|---|---|---|---|
top_on_partner |
object |
یکی از | نامزد مورد برتر رتبهبندیشده در سرویس شما است. حاوی یک فیلد عدد صحیح مثبت rank است (برای مثال، {"rank": 1} برای «Top 1 on Partner»). |
popular_on_partner |
object |
یکی از | نامزد در سرویس شما محبوب است. شیء خالی ({}) را ارسال کنید. |
new_on_partner |
object |
یکی از | نامزد در سرویس شما جدید است. شیء خالی ({}) را ارسال کنید. |
generic |
object |
یکی از | دلیل سفارشی. حاوی یک فیلد LocalizedString تکی generic_reason است (LocalizedString را ببینید). هر مقدار ۱ تا ۱۰۰ نقطه کد «یونیکد» است. |
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} نشاندهنده ۱۷ ژانویه ۲۰۲۵ است،
{"year": 2025, "month": 1} نشاندهنده ژانویه ۲۰۲۵ با روز نامشخص است،
و {"year": 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 کد HTTP 200 OK را با بدنه
ReplaceCandidatesResponse برمیگرداند:
| فیلد | نوع | شرح |
|---|---|---|
replaced_candidates_count |
integer (int32) |
تعداد نامزدهای جایگزینشده. |
برای درخواست نمونه قبلی، پاسخ این است:
{
"replaced_candidates_count": 3
}
رفتار جایگزین
درک نحوه بهروزرسانی نامزدهای ذخیرهشده توسط replaceCandidates برای طراحی ادغام شما ضروری است:
- جایگزینی کامل در هر فید. هر تماس بهطور کامل جایگزین فهرست نامزدهای ذخیرهشده قبلی برای فید نامگذاریشده در مسیر نشانی وب میشود. همیشه مجموعه کامل نامزدهای فعال را برای آن فید ارسال کنید.
- فیدهای دیگر بدون تغییر باقی میمانند. فیدهایی که نامزدها را به آنها ارسال نمیکنید تا زمانی که این کار را انجام ندهید بدون تغییر باقی میمانند. برای مثال، جایگزین کردن نامزدهای یک فید، نامزدهای ذخیرهشده شما را برای هیچ فید دیگری تغییر نمیدهد و جایگزین کردن نامزدهای
{recommendationsFeed}-staging،{recommendationsFeed}را تغییر نمیدهد. - یک تماس برای هر فید. برای بهروزرسانی چند فید، برای هر فید یک تماس برقرار کنید. فراخوانیها مستقل هستند: اگر یکی ناموفق باشد، فیدهای دیگر نامزدهای جدید خود را حفظ میکنند و شما فقط فراخوانی ناموفق را دوباره امتحان میکنید.
- فیدهای فعال را حداقل هر ۳۰ روز یکبار دوباره ارسال کنید. حتی اگر کاتالوگ شما برای یک فید تغییر نکرده است، هر فید فعال را حداقل یک بار در هر ۳۰ روز (یا طبق یک برنامه منظم روزانه یا هفتگی با لرزش تصادفی) دوباره ارسال کنید تا نامزدهای شما فعال بمانند و منقضی نشوند. تنظیم
availability_intervalsend_timeدر آینده دور جایگزین ارسال مجدد دورهای نمیشود. - اجرای اتمی. میانای برنامهسازی کاربردی درخواست را بهصورت اتمی اعمال میکند. اگر هرکدام از نامزدها اعتبارسنجی نشود، API کل درخواست را رد میکند و فید نامزدهای قبلی خود را حفظ میکند.