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