دمج الاقتراحات باستخدام REST API

تتيح واجهة برمجة التطبيقات REST API الخاصة بميزة "اكتشاف الفيديوهات" في Google TV للشركاء إرسال اقتراحات غير مخصّصة إلى أجهزة Google TV وAndroid TV من خوادمهم الخلفية. يؤدي إرسال المرشحين من الخلفية إلى الحفاظ على تحديث كتالوج الشريك وتوصيات البرامج المباشرة على هذه الأجهزة دون مطالبة المستخدمين بفتح تطبيق الشريك.

يرسل الشركاء المحتوى المرشّح إلى خلاصات الاقتراحات. تنشئ Google كل خلاصة للشريك وتضبط البلدان أو المناطق ولغات أجهزة التلفزيون التي تظهر الخلاصة فيها. يمكن أن تتضمّن الخلاصة أفلامًا وبرامج تلفزيونية وبثًا تلفزيونيًا مباشرًا.

إذا أردت نشر اقتراحات مخصّصة من جهاز المستخدم، يُرجى الاطّلاع على دمج الاقتراحات على الجهاز فقط باستخدام حزمة Engage SDK.

المتطلبات الأساسية

قبل الدمج مع REST API، تأكَّد من توفّر ما يلي:

  • مشروع على Google Cloud لإرسال طلبات البيانات من واجهة برمجة التطبيقات منه
  • حساب Google Workspace مرتبط بمؤسستك
  • معرّف الشريك ومعرّفات خلاصة الاقتراحات التي يقدّمها ممثل شريك Google TV أثناء عملية الإعداد يُرجى الاطّلاع على خلاصات الاقتراحات لمعرفة كيفية استخدام هذه المعرّفات.

اكسب المزايا

يقتصر الوصول إلى واجهة برمجة التطبيقات REST API الخاصة بميزة "اكتشاف الفيديوهات" في Google TV على شركاء Google TV المسجّلين في مجال الوسائط. تتم مصادقة كل متصل باستخدام حساب خدمة Google Cloud مرتبط على الخادم بمعرّف شريك واحد بالضبط.

لطلب الوصول إلى واجهة برمجة التطبيقات وضبطه، اتّبِع الخطوات التالية:

  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 التالي وأرسِل الرمز المميز في عنوان HTTP‏ Authorization: Bearer في كل طلب:

    https://www.googleapis.com/auth/tvvideodiscovery
    

الحدود القصوى لمعدّل الاستخدام

تخضع الطلبات إلى replaceCandidates لحدود معدّل الطلبات التالية لكل مشروع والحدود القصوى لحمولة البيانات لكل طلب:

الحدّ المسموح به القيمة
عدد الطلبات في الدقيقة لكل مشروع على السحابة الإلكترونية على Google Cloud 5
عدد الطلبات اليومية لكل مشروع على السحابة الإلكترونية على Google Cloud 100
‫RecommendationCandidate عنصر لكل طلب من 1 إلى 25

يتم احتساب الطلبات المرسَلة إلى خلاصة مرحلية ضمن الحصة نفسها المخصّصة للطلبات المرسَلة إلى خلاصة الإنتاج المقابلة.

خلاصات الاقتراحات

تنظّم واجهة برمجة التطبيقات الاقتراحات المرشّحة في خلاصات الاقتراحات. يتم تحديد الخلاصة من خلال اسم مورد بالتنسيق التالي:

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

يحتوي مسار عنوان URL على اسم المورد للخلاصة التي يتم استبدال العناصر المرشحة فيها. يحتوي نص الطلب على كل حقل ليس جزءًا من مسار عنوان URL.

مَعلمات المسار

المَعلمة الوصف
name مطلوب. اسم مورد الخلاصة، بالتنسيق partners/{partner}/recommendationsFeeds/{recommendationsFeed}. يجب أن يكون {partner} هو معرّف الشريك الذي تم ربط حساب الخدمة به. يجب أن يكون {recommendationsFeed} معرّف خلاصة أنشأته Google لهذا الشريك، أو معرّف الخلاصة هذا مع اللاحقة -staging.

ReplaceCandidatesRequest

يتضمن نص طلب JSON البنية التالية:

الحقل النوع مطلوب الوصف
recommendation_candidates array of RecommendationCandidate نعم قائمة تتضمّن من عنصر واحد إلى 25 عنصرًا من النوع 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). تتراوح كل قيمة بين 1 و100 قيمة موضع رمز يونيكود ويتم عرضها كما تم إرسالها.
description LocalizedString نعم وصف قصير للفيلم (راجِع LocalizedString). تتراوح كل قيمة بين 1 و400 قيمة موضع رمز يونيكود.
localized_media_images array of LocalizedMediaImage نعم صور عمل فني بنسبة عرض إلى ارتفاع 16:9، وإدخال واحد لكل لغة (يُرجى الاطّلاع على LocalizedMediaImage). يجب أن تحتوي على صورة واحدة على الأقل. يُرجى تقديم أكبر مصدر متاح، ويُنصح باستخدام ‎1920x1080 بكسل.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri نعم الروابط العميقة لكل نظام أساسي ولكل لغة (يُرجى الاطّلاع على LocalizedProviderPlaybackUri). يجب أن يتضمّن إدخال واحد على الأقل PLATFORM_ANDROID_TV.
release_date Date نعم تاريخ إصدار الفيلم (يُرجى الاطّلاع على Date).
external_entity_ids array of ExternalEntityId لا معرّفات الكتالوجات الخارجية لمطابقة الكيانات (يُرجى الاطّلاع على ExternalEntityId). يُسمح بإدخال واحد كحدّ أقصى لكل نوع معرّف.
duration ‫string ‎(Duration) لا مدة الفيلم (يُرجى الاطّلاع على Duration)، مثل "7200s" لمدة ساعتين
content_ratings array of ContentRating لا التقييمات الرسمية للمحتوى (يُرجى الاطّلاع على ContentRating).

TvShowCandidate

يمثّل العنصر TvShowCandidate برنامجًا تلفزيونيًا على مستوى البرنامج. تعرض أجهزة Google TV وAndroid TV بطاقة للبرنامج، ويمكنك استخدام الرابط لصفحة معيّنة لتحديد ما إذا كان سيتم بدء التشغيل على صفحة البرنامج أو على حلقة معيّنة.

الحقل النوع مطلوب الوصف
title LocalizedString نعم عنوان البرنامج التلفزيوني (يُرجى الاطّلاع على LocalizedString). تتراوح كل قيمة بين 1 و100 قيمة موضع الرمز يونيكود وتظهر كما تم إرسالها.
description LocalizedString نعم وصف قصير للبرنامج التلفزيوني (يُرجى الاطّلاع على LocalizedString). تتراوح كل قيمة بين نقطة رمز يونيكود واحدة و400 نقطة.
localized_media_images array of LocalizedMediaImage نعم صور عمل فني بنسبة عرض إلى ارتفاع 16:9، وإدخال واحد لكل لغة (يُرجى الاطّلاع على LocalizedMediaImage). يجب أن تحتوي على صورة واحدة على الأقل. يُرجى تقديم أكبر مصدر متاح، ويُنصح باستخدام ‎1920x1080 بكسل.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri نعم الروابط العميقة لكل نظام أساسي ولكل لغة (يُرجى الاطّلاع على LocalizedProviderPlaybackUri). يجب أن يتضمّن إدخال واحد على الأقل PLATFORM_ANDROID_TV. يمكن أن يشير uri إلى صفحة البرنامج أو إلى حلقة.
first_episode_air_date Date نعم تاريخ البث المباشر للحلقة الأولى (راجِع Date).
external_entity_ids array of ExternalEntityId لا معرّفات الكتالوجات الخارجية لمطابقة الكيانات (يُرجى الاطّلاع على ExternalEntityId). يُسمح بإدخال واحد كحدّ أقصى لكل نوع معرّف.
season_count integer (int32) لا عدد المواسم المتاحة في خدمتك
content_ratings array of ContentRating لا التقييمات الرسمية للمحتوى (يُرجى الاطّلاع على ContentRating).

LiveTvProgramCandidate

يمثّل العنصر LiveTvProgramCandidate بثًا تلفزيونيًا مباشرًا أو حدثًا يتم بثه مباشرةً. تُعدّ نافذة البث جزءًا من المرشّح، وهي منفصلة عن availability_intervals المرشّح الرئيسي الذي يتحكّم في وقت عرض البطاقة.

الحقل النوع مطلوب الوصف
title LocalizedString نعم عنوان برنامج البث التلفزيوني المباشر (يُرجى الاطّلاع على LocalizedString). تتراوح كل قيمة بين 1 و100 قيمة موضع رمز يونيكود، وتظهر كما تم إرسالها.
description LocalizedString نعم وصف قصير لبرنامج البث التلفزيوني المباشر (يُرجى الاطّلاع على LocalizedString). تتراوح كل قيمة بين 1 و400 قيمة موضع رمز يونيكود.
localized_media_images array of LocalizedMediaImage نعم صور عمل فني بنسبة عرض إلى ارتفاع 16:9، وإدخال واحد لكل لغة (يُرجى الاطّلاع على LocalizedMediaImage). يجب أن تحتوي على صورة واحدة على الأقل. يُرجى تقديم أكبر مصدر متاح، ويُنصح باستخدام ‎1920x1080 بكسل.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri نعم الروابط العميقة لكل نظام أساسي ولكل لغة (يُرجى الاطّلاع على LocalizedProviderPlaybackUri). يجب أن يتضمّن إدخال واحد على الأقل PLATFORM_ANDROID_TV.
broadcast_interval Interval نعم وقت بدء البرنامج وانتهائه (راجِع Interval). يجب إدخال كل من start_time وend_time.
external_entity_ids array of ExternalEntityId لا معرّفات الكتالوجات الخارجية لمطابقة الكيانات (يُرجى الاطّلاع على 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 نعم صورة بنسبة عرض إلى ارتفاع 16:9 (راجِع MediaImage). قدِّم أكبر مصدر متاح، ويُنصح باستخدام ‎1920x1080 بكسل.

LocalizedProviderPlaybackUri

يقرن عنصر LocalizedProviderPlaybackUri رابطًا لصفحة في التطبيق بلغة المحتوى الذي يفتحه والتطبيق الذي يفتحه:

الحقل النوع مطلوب الوصف
playback_uri PlaybackUri نعم الرابط لصفحة معيّنة والأنظمة الأساسية التي ينطبق عليها (يُرجى الاطّلاع على PlaybackUri).
language_code string نعم رمز لغة BCP-47 للمحتوى الذي يفتحه الرابط العميق، مثل "en-US" أو "sr-Latn".
package_name string نعم اسم حزمة تطبيق Android المستخدَم لفتح الرابط العميق (على سبيل المثال، "com.example.tvapp").

PlaybackUri

يحدّد عنصر PlaybackUri رابطًا عميقًا والأنظمة الأساسية المستهدَفة:

الحقل النوع مطلوب الوصف
uri string نعم معرّف الموارد المنتظم (URI) للرابط لصفحة معيّنة في التطبيق الذي يبدأ تشغيل المحتوى المرشّح في تطبيقك
platforms array of string (enum) نعم تمثّل هذه السمة الأنظمة الأساسية التي ينطبق عليها هذا الرابط لصفحة معيّنة. القيم المسموح بها: PLATFORM_UNSPECIFIED وPLATFORM_ANDROID_TV وPLATFORM_ANDROID وPLATFORM_IOS. تضمين 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} لـ "أفضل 1 على الشريك").
popular_on_partner object أحد الخيارات التالية: المحتوى المرشَّح رائج في خدمتك. مرِّر عنصرًا فارغًا ({}).
new_on_partner object أحد الخيارات التالية: المرشّح جديد في خدمتك. مرِّر عنصرًا فارغًا ({}).
generic object أحد الخيارات التالية: سبب مخصّص يحتوي على حقل LocalizedString واحد generic_reason (يُرجى الاطّلاع على LocalizedString). تتراوح كل قيمة بين 1 و100 قيمة موضع رمز يونيكود.

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

إذا نجح الطلب، ستعرض واجهة برمجة التطبيقات رمز الحالة HTTP 200 OK مع نص ReplaceCandidatesResponse:

الحقل النوع الوصف
replaced_candidates_count integer (int32) عدد المرشحين الذين تم استبدالهم

بالنسبة إلى مثال الطلب السابق، تكون الاستجابة كما يلي:

{
  "replaced_candidates_count": 3
}

سلوك الاستبدال

من الضروري فهم كيفية تعديل replaceCandidates للمرشحين المخزَّنين لتصميم عملية الدمج:

  • الاستبدال الكامل لكل خلاصة: يؤدي كل طلب إلى استبدال قائمة المرشحين المخزنة مسبقًا بالكامل للخلاصة المذكورة في مسار عنوان URL. يجب دائمًا إرسال المجموعة الكاملة من المرشحين النشطين لتلك الخلاصة.
  • تبقى الخلاصات الأخرى بدون تغيير. تبقى الخلاصات التي لا ترسل إليها المرشحين بدون تغيير حتى ترسل إليها. على سبيل المثال، لا يؤدي استبدال المرشحين في خلاصة واحدة إلى تعديل المرشحين المخزنين لأي خلاصة أخرى، ولا يؤدي استبدال المرشحين في {recommendationsFeed}-staging إلى تعديل {recommendationsFeed}.
  • طلب واحد لكل خلاصة: لتعديل عدة خلاصات، عليك إجراء طلب واحد لكل خلاصة. الطلبات مستقلة: إذا تعذّر تنفيذ أحدها، تحتفظ الخلاصات الأخرى بالمرشحين الجدد، ويمكنك إعادة محاولة الطلب الذي تعذّر تنفيذه فقط.
  • أعِد إرسال الخلاصات النشطة كل 30 يومًا على الأقل. حتى إذا لم يتغيّر الكتالوج الخاص بخلاصة معيّنة، يجب إعادة إرسال كل خلاصة نشطة مرة واحدة على الأقل كل 30 يومًا (أو وفقًا لجدول زمني يومي أو أسبوعي منتظم مع تفاوت عشوائي) لكي تظلّ المرشّحات نشطة ولا تنتهي صلاحيتها. لا يحلّ ضبط availability_intervals end_time في المستقبل البعيد محلّ إعادة الإرسال بشكل دوري.
  • التنفيذ الذري: تطبّق واجهة برمجة التطبيقات الطلب بشكل ذري. إذا تعذّر التحقّق من صحة أي مرشّح، ترفض واجهة برمجة التطبيقات الطلب بالكامل وتحتفظ الخلاصة بالمرشّحين السابقين.