REST API का इस्तेमाल करके सुझावों को इंटिग्रेट करना

Google TV वीडियो डिस्कवरी REST API की मदद से, पार्टनर अपने बैकएंड सर्वर से Google TV और Android TV डिवाइसों पर, लोगों के हिसाब से न दिखाए जाने वाले सुझाव भेज सकते हैं. बैकएंड से कैंडिडेट भेजने पर, पार्टनर का कैटलॉग और लाइव प्रोग्रामिंग के सुझाव इन डिवाइसों पर अपडेट रहते हैं. इसके लिए, उपयोगकर्ताओं को पार्टनर का ऐप्लिकेशन खोलने की ज़रूरत नहीं पड़ती.

पार्टनर, सुझाव फ़ीड में उम्मीदवारों की जानकारी भेजते हैं. Google, पार्टनर के लिए हर फ़ीड बनाता है. साथ ही, उन देशों या इलाकों और टीवी डिवाइस की भाषाओं को कॉन्फ़िगर करता है जिनमें फ़ीड दिखाया जाता है. फ़ीड में फ़िल्में, टीवी शो, और लाइव टीवी प्रोग्राम शामिल हो सकते हैं.

अगर आपको उपयोगकर्ता के डिवाइस पर, उसकी दिलचस्पी के हिसाब से सुझाव पब्लिश करने हैं, तो Engage SDK टूल का इस्तेमाल करके, डिवाइस पर सुझाव इंटिग्रेट करना लेख पढ़ें.

ज़रूरी शर्तें

REST API के साथ इंटिग्रेट करने से पहले, पक्का करें कि आपके पास ये चीज़ें हों:

  • एपीआई अनुरोध करने के लिए, एक Google Cloud प्रोजेक्ट.
  • आपके संगठन से जुड़ा Google Workspace खाता.
  • आपका पार्टनर आईडी और सुझाव फ़ीड आईडी. ये आईडी, Google TV पार्टनर के प्रतिनिधि ने आपको शामिल होने के दौरान दिए होंगे. इन आईडी का इस्तेमाल कैसे किया जाता है, यह जानने के लिए सुझावों के फ़ीड देखें.

ऐक्सेस पाएं

Google TV Video Discovery REST API का ऐक्सेस, सिर्फ़ 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 TV पार्टनर के प्रतिनिधि को अपना Google Workspace ग्राहक आईडी, Google Cloud प्रोजेक्ट आईडी, और सेवा खाते का ईमेल पता (या यूनीक न्यूमेरिक आईडी) दें. साथ ही, उन देशों या इलाकों और टीवी डिवाइस की भाषाओं की जानकारी दें जिनके लिए आपको कॉन्टेंट के सुझाव भेजने हैं. Google TV पार्टनर का प्रतिनिधि, आपके Google Workspace संगठन, प्रोजेक्ट, और सेवा खाते को आपके पार्टनर आईडी से मैप करने के बाद आपको इसकी सूचना देता है. साथ ही, आपको आपके पार्टनर के लिए बनाए गए सुझाव फ़ीड के आईडी देता है.
  5. एपीआई को चालू करें और क्रेडेंशियल जनरेट करें. जब आपका प्रतिनिधि ऐक्सेस मिलने की पुष्टि कर दे, तब अपने Google Cloud प्रोजेक्ट में Google TV Video Discovery API (tvvideodiscovery.googleapis.com) को चालू करें. साथ ही, अपने सेवा खाते के लिए OAuth 2.0 क्रेडेंशियल जनरेट करें.
  6. अपने अनुरोधों की पुष्टि करना. यहां दिए गए OAuth स्कोप का इस्तेमाल करके, OAuth 2.0 ऐक्सेस टोकन का अनुरोध करें. साथ ही, हर कॉल पर 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 तरीके का इस्तेमाल करें.

एचटीटीपी अनुरोध

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 हां 1 से 25 RecommendationCandidate आइटम की सूची. ये उम्मीदवार, फ़ीड के मौजूदा उम्मीदवारों की जगह ले लेते हैं.

संभावित स्कीमा

recommendation_candidates में मौजूद हर आइटम, एक RecommendationCandidate ऑब्जेक्ट होता है. इसमें एक कैंडिडेट-टाइप पेलोड, सुझाव देने की वैकल्पिक वजहें, और डिसप्ले की उपलब्धता की वैकल्पिक विंडो शामिल होती हैं.

RecommendationCandidate

RecommendationCandidate ऑब्जेक्ट में, मीडिया टाइप के पेलोड फ़ील्ड की सिर्फ़ एक वैल्यू होती है. साथ ही, इसमें सुझाव देने की वजहें और उपलब्धता के इंटरवल की जानकारी भी शामिल होती है. हालांकि, ये दोनों ज़रूरी नहीं हैं.

यूनियन फ़ील्ड candidate_type

candidate_type ज़रूरी है: इनमें से सिर्फ़ एक फ़ील्ड सेट करें. ये फ़ील्ड एक-दूसरे से अलग होते हैं. अगर कोई उम्मीदवार इनमें से किसी भी फ़ील्ड को सेट नहीं करता है या एक से ज़्यादा फ़ील्ड सेट करता है, तो उसे अस्वीकार कर दिया जाता है. JSON में कोई candidate_type कुंजी नहीं है. चुने गए फ़ील्ड को सीधे 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 हां text का BCP-47 भाषा कोड, जैसे कि "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 हां डीप लिंक यूआरआई, जो आपके ऐप्लिकेशन में कैंडिडेट को चलाना शुरू करता है.
platforms array of string (enum) हां वे प्लैटफ़ॉर्म जिन पर यह डीप लिंक लागू होता है. इस्तेमाल की जा सकने वाली वैल्यू: PLATFORM_UNSPECIFIED, PLATFORM_ANDROID_TV, PLATFORM_ANDROID, PLATFORM_IOS. Google TV और Android TV डिवाइसों के लिए, PLATFORM_ANDROID_TV शामिल करें.

MediaImage

MediaImage ऑब्जेक्ट, इमेज के यूआरएल, उसके पिक्सल डाइमेंशन, और सुलभता टेक्स्ट के बारे में बताता है:

फ़ील्ड प्रकार ज़रूरी है ब्यौरा
url string हां इमेज का एचटीटीपीएस यूआरएल, जिसे सार्वजनिक तौर पर ऐक्सेस किया जा सकता हो.
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 शामिल होता है. उदाहरण के लिए, "पार्टनर पर टॉप 1" के लिए {"rank": 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 में, यूटीसी में आरएफ़सी 3339 स्ट्रिंग के तौर पर एन्कोड किया जाता है. इसमें 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 के बाद की तारीख होनी चाहिए.

अनुरोध का उदाहरण

यहां दिए गए उदाहरण में, पार्टनर example-partner के फ़ीड in-en-cricket के कैंडिडेट को तीन कैंडिडेट (एक फ़िल्म, एक टीवी शो, और एक लाइव टीवी प्रोग्राम) से बदल दिया गया है. फ़िल्म में दो भाषाओं में टेक्स्ट मौजूद है:

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"
          }
        ]
      }
    ]
  }'

जवाब और बदलाव से जुड़ा व्यवहार

इस सेक्शन में, replaceCandidates से मिले एचटीटीपी रिस्पॉन्स के बारे में बताया गया है. साथ ही, यह भी बताया गया है कि हर कॉल, सेव किए गए उम्मीदवारों को कैसे अपडेट करता है.

ReplaceCandidatesResponse

अगर अनुरोध पूरा हो जाता है, तो एपीआई, ReplaceCandidatesResponse बॉडी के साथ एचटीटीपी 200 OK दिखाता है:

फ़ील्ड प्रकार ब्यौरा
replaced_candidates_count integer (int32) बदले गए उम्मीदवारों की संख्या.

पिछले अनुरोध के उदाहरण के लिए, जवाब यह है:

{
  "replaced_candidates_count": 3
}

बदलाव का तरीका

इंटिग्रेशन को डिज़ाइन करने के लिए, यह समझना ज़रूरी है कि replaceCandidates, सेव किए गए उम्मीदवारों की जानकारी को कैसे अपडेट करता है:

  • हर फ़ीड के लिए पूरी तरह से बदलाव करना. हर कॉल, यूआरएल पाथ में बताए गए फ़ीड के लिए, पहले से सेव की गई कैंडिडेट लिस्ट को पूरी तरह से बदल देता है. उस फ़ीड के लिए, हमेशा ऐक्टिव कैंडिडेट का पूरा सेट भेजें.
  • अन्य फ़ीड में कोई बदलाव नहीं होगा. जिन फ़ीड में कैंडिडेट नहीं भेजे जाते हैं उनमें तब तक कोई बदलाव नहीं होता, जब तक आप ऐसा न करें. उदाहरण के लिए, किसी एक फ़ीड के कैंडिडेट बदलने से, किसी दूसरे फ़ीड के लिए सेव किए गए कैंडिडेट में कोई बदलाव नहीं होता. साथ ही, {recommendationsFeed}-staging के कैंडिडेट बदलने से, {recommendationsFeed} में कोई बदलाव नहीं होता.
  • हर फ़ीड के लिए एक कॉल. कई फ़ीड अपडेट करने के लिए, हर फ़ीड के लिए एक कॉल करें. कॉल एक-दूसरे पर निर्भर नहीं होते: अगर कोई कॉल पूरा नहीं हो पाता है, तो अन्य फ़ीड अपने नए कैंडिडेट को बनाए रखते हैं और आपको सिर्फ़ उस कॉल को फिर से करना होता है जो पूरा नहीं हो पाया.
  • ऐक्टिव फ़ीड को कम से कम हर 30 दिन में फिर से भेजें. अगर किसी फ़ीड के लिए आपका कैटलॉग नहीं बदला है, तो भी हर चालू फ़ीड को हर 30 दिन में कम से कम एक बार फिर से भेजें. इसके अलावा, रैंडम जिटर के साथ रोज़ या हफ़्ते के शेड्यूल पर भी फ़ीड भेजा जा सकता है. इससे आपके उम्मीदवारों की जानकारी चालू रहती है और उसकी समयसीमा खत्म नहीं होती. availability_intervals end_time को आने वाले समय में बहुत आगे सेट करने से, समय-समय पर फिर से भेजने की सुविधा नहीं बदलती.
  • ऐटॉमिक एक्ज़ीक्यूशन. एपीआई, अनुरोध को एक साथ लागू करता है. अगर कोई भी कैंडिडेट पुष्टि की प्रोसेस पूरी नहीं कर पाता है, तो एपीआई पूरे अनुरोध को अस्वीकार कर देता है. साथ ही, फ़ीड में पिछले कैंडिडेट बने रहते हैं.