ادغام کردن توصیه‌ها بااستفاده از REST API

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، این مراحل را دنبال کنید:

  1. ایجاد کردن حساب Google Workspace. دستورالعمل‌های موجود در صفحه پشتیبانی Google Workspace را برای راه‌اندازی حساب برای سازمانتان دنبال کنید.
  2. «شناسه مشتری» Google Workspace خود را پیدا کنید. با دنبال کردن مراحل موجود در پیدا کردن شناسه مشتری، «شناسه مشتری» خود را (برای مثال، C0123abcd) پیدا کنید.
  3. پروژه Google Cloud و حساب خدمات ایجاد کنید. در Google Cloud Console در سازمان Google Workspace، پروژه Google Cloud و حساب سرویس برای سرور زیرینه خود ایجاد کنید.
  4. درخواست آماده‌سازی شریک. شناسه مشتری Google Workspace، شناسه پروژه Google Cloud، و نشانی ایمیل حساب سرویس (یا شناسه عددی یکتا) خود را به‌همراه کشورها یا مناطق و زبان‌های دستگاه تلویزیونی که می‌خواهید نامزدها را به آن‌ها ارسال کنید، به نماینده شریک Google TV خود ارائه دهید. نماینده شریک Google TV شما پس‌از نگاشت سازمان، پروژه، و حساب سرویس Google Workspace شما به شناسه شریکتان، به شما اطلاع می‌دهد و شناسه‌های فید توصیه‌های ایجادشده برای شریکتان را به شما می‌دهد.
  5. میانای برنامه‌سازی کاربردی را فعال کنید و اطلاعات کاربری تولید کنید. پس‌از اینکه نماینده‌تان تأیید کرد دسترسی اعطا شده است، Google TV Video Discovery API (tvvideodiscovery.googleapis.com) را در پروژه Google Cloud خود فعال کنید و اعتبارنامه OAuth 2.0 را برای حساب سرویس خود تولید کنید.
  6. درخواست‌هایتان را اصالت‌سنجی کنید. درخواست کدهای دسترسی OAuth 2.0 بااستفاده از دامنه OAuth زیر و ارسال کد در سرایند Authorization: Bearer HTTP در هر تماس:

    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_intervals end_time در آینده دور جایگزین ارسال مجدد دوره‌ای نمی‌شود.
  • اجرای اتمی. میانای برنامه‌سازی کاربردی درخواست را به‌صورت اتمی اعمال می‌کند. اگر هرکدام از نامزدها اعتبارسنجی نشود، API کل درخواست را رد می‌کند و فید نامزدهای قبلی خود را حفظ می‌کند.