YouTube Data API की खास जानकारी

परिचय

यह दस्तावेज़ उन डेवलपर के लिए है जो YouTube के साथ इंटरैक्ट करने वाले ऐप्लिकेशन लिखना चाहते हैं. यह YouTube और एपीआई के बुनियादी सिद्धांतों के बारे में बताता है. इससे, इस एपीआई पर काम करने वाले अलग-अलग फ़ंक्शन की खास जानकारी भी मिलती है.

शुरू करने से पहले

1. Google API कंसोल को ऐक्सेस करने, एपीआई पासकोड का अनुरोध करने, और अपना ऐप्लिकेशन रजिस्टर करने के लिए, आपके पास एक Google खाता होना चाहिए.

2. Google Developers Console में एक प्रोजेक्ट बनाएं और अनुमति देने वाले क्रेडेंशियल पाएं, ताकि आपका ऐप्लिकेशन एपीआई अनुरोध सबमिट कर सके.

3. अपना प्रोजेक्ट बनाने के बाद, पक्का करें कि YouTube Data API उन सेवाओं में से एक है जिसका इस्तेमाल करने के लिए आपका ऐप्लिकेशन रजिस्टर किया गया है:

   1. एपीआई कंसोल पर जाएं और वह प्रोजेक्ट चुनें जिसे आपने अभी-अभी रजिस्टर किया है.
   2. चालू किए गए एपीआई पेज पर जाएं. एपीआई की सूची में, पक्का करें कि YouTube Data API v3 के लिए स्थिति चालू है.

4. अगर आपका ऐप्लिकेशन ऐसे एपीआई के तरीकों का इस्तेमाल करेगा जिनके लिए उपयोगकर्ता की अनुमति ज़रूरी है, तो OAuth 2.0 के लिए अनुमति लागू करने का तरीका जानने के लिए, पुष्टि करने से जुड़ी गाइड पढ़ें.

5. अपने एपीआई को आसानी से लागू करने के लिए, क्लाइंट लाइब्रेरी चुनें.

6. JSON (JavaScript ऑब्जेक्ट नोटेशन) डेटा फ़ॉर्मैट के मुख्य सिद्धांतों के बारे में जानें. JSON एक सामान्य और भाषा पर निर्भर डेटा फ़ॉर्मैट है, जो आर्बिट्रेरी डेटा स्ट्रक्चर को सामान्य टेक्स्ट में दिखाता है. ज़्यादा जानकारी के लिए, json.org पर जाएं.

संसाधन और अलग-अलग तरह के संसाधन

संसाधन, एक यूनीक आइडेंटिफ़ायर वाली व्यक्तिगत डेटा इकाई होता है. नीचे दी गई टेबल में अलग-अलग तरह के संसाधनों के बारे में बताया गया है. एपीआई का इस्तेमाल करके, इन संसाधनों का इस्तेमाल किया जा सकता है.

ध्यान दें कि कई मामलों में, एक संसाधन में अन्य संसाधनों के संदर्भ होते हैं. उदाहरण के लिए, playlistItem संसाधन की snippet.resourceId.videoId प्रॉपर्टी ऐसे वीडियो रिसॉर्स की पहचान करती है जिसमें वीडियो के बारे में पूरी जानकारी होती है. एक अन्य उदाहरण के तौर पर, किसी खोज नतीजे में videoId, playlistId या channelId प्रॉपर्टी शामिल होती है, जो किसी खास वीडियो, प्लेलिस्ट या चैनल संसाधन की पहचान करती है.

काम करने वाली कार्रवाइयां

नीचे दी गई टेबल में, एपीआई इस्तेमाल करने के सबसे आम तरीके बताए गए हैं. कुछ संसाधन ऐसे अन्य तरीकों के साथ भी काम करते हैं जो उन संसाधनों के हिसाब से फ़ंक्शन करते हैं. उदाहरण के लिए, videos.rate तरीका, उपयोगकर्ता की रेटिंग को वीडियो से जोड़ता है. साथ ही, thumbnails.set तरीका, YouTube पर वीडियो के थंबनेल की इमेज अपलोड करके उसे वीडियो से जोड़ता है.

फ़िलहाल, एपीआई पर काम करने वाले हर तरह के संसाधन की सूची बनाने के तरीके दिए गए हैं. साथ ही, यह कई संसाधनों के लिए लिखने के काम भी करता है.

नीचे दी गई टेबल में उन कार्रवाइयों के बारे में बताया गया है जो अलग-अलग तरह के संसाधनों के लिए काम करती हैं. संसाधन डालने, अपडेट करने या मिटाने वाली कार्रवाइयों के लिए, हमेशा उपयोगकर्ता की अनुमति की ज़रूरत होती है. कुछ मामलों में, list के तरीकों में अनुमति वाले और बिना मंज़ूरी वाले, दोनों तरह के अनुरोध काम करते हैं. इनमें बिना अनुमति वाले अनुरोध सिर्फ़ सार्वजनिक डेटा हासिल करते हैं, जबकि अनुमति वाले अनुरोध भी उस मौजूदा उपयोगकर्ता के बारे में जानकारी दे सकते हैं या उसे निजी बना सकते हैं जिसकी पुष्टि हो चुकी है.

इस्तेमाल किया गया कोटा

YouTube Data API, कोटा का इस्तेमाल यह पक्का करने के लिए करता है कि डेवलपर उम्मीद के मुताबिक सेवा का इस्तेमाल करें. साथ ही, वे ऐसे ऐप्लिकेशन न बनाएं जो सेवा की क्वालिटी को गलत तरीके से कम करते हों या दूसरों के लिए इसका ऐक्सेस सीमित करते हों. सभी एपीआई अनुरोधों के लिए, कम से कम एक पॉइंट का कोटा खर्च होता है. इनमें अमान्य अनुरोध भी शामिल हैं. आप API Console में अपने आवेदन के लिए उपलब्ध कोटा देख सकते हैं.

YouTube Data API चालू करने वाले प्रोजेक्ट में,हर दिन डिफ़ॉल्ट तौर पर 10, 000 यूनिट यूनिट होती हैं. यह हमारे एपीआई का इस्तेमाल करने वाले ज़्यादातर लोगों के लिए काफ़ी है. डिफ़ॉल्ट कोटा बदला जा सकता है. इससे हमें कोटा के बंटवारे को ऑप्टिमाइज़ करने और अपने इंफ़्रास्ट्रक्चर को इस तरह से बढ़ाने में मदद मिलती है जो हमारे एपीआई उपयोगकर्ताओं के लिए ज़्यादा काम का हो. एपीआई कंसोल में, कोटा पेज पर जाकर, कोटा के इस्तेमाल की जानकारी देखी जा सकती है.

ध्यान दें: तय सीमा तक पहुंचने पर, अतिरिक्त कोटे का अनुरोध किया जा सकता है अपने कोटा एक्सटेंशन की प्रक्रिया पूरी करना YouTube API की सेवाओं के लिए अनुरोध फ़ॉर्म भरें.

कोटा के इस्तेमाल की गणना की जा रही है

Google हर अनुरोध के लिए एक लागत तय करके, आपके कोटे के इस्तेमाल का हिसाब लगाता है. अलग-अलग तरह के ऑपरेशन की लागत अलग-अलग होती है. उदाहरण के लिए:

• रीड ऑपरेशन, जो आम तौर पर संसाधनों की सूची -- चैनल, वीडियो, प्लेलिस्ट -- को फिर से हासिल करता है 1 इकाई की लागत.
• आम तौर पर, संसाधन बनाने, अपडेट करने या मिटाने वाली राइट ऑपरेशन की लागत होती है 50 इकाइयां.
• खोज के अनुरोध की लागत 100 यूनिट होती है.
• एक वीडियो अपलोड करने की कीमत 1600 यूनिट होती है.

एपीआई अनुरोधों के लिए कोटा की लागतें टेबल में एपीआई के हर तरीके के लिए कोटा की कीमत. इन नियमों को ध्यान में रखते हुए, आपके पास हर तरह के अनुरोध जिसे आपका ऐप्लिकेशन आपके कोटे को पार किए बिना हर दिन भेज सके.

सीमित संसाधन

एपीआई, आंशिक संसाधनों को वापस लाने की अनुमति देता है और असल में इनकी ज़रूरत होती है. इससे ऐप्लिकेशन, ग़ैर-ज़रूरी डेटा ट्रांसफ़र, पार्स, और सेव नहीं करते. इससे यह भी पक्का होता है कि एपीआई, नेटवर्क, CPU, और मेमोरी संसाधनों का बेहतर तरीके से इस्तेमाल करता है.

एपीआई में दो अनुरोध पैरामीटर इस्तेमाल किए जा सकते हैं, जिनके बारे में नीचे दिए गए सेक्शन में बताया गया है. इनकी मदद से, उन रिसॉर्स प्रॉपर्टी की पहचान की जा सकती है जिन्हें एपीआई के रिस्पॉन्स में शामिल किया जाना चाहिए.

• part पैरामीटर, प्रॉपर्टी के उन ग्रुप की पहचान करता है जिन्हें किसी संसाधन के लिए दिखाया जाना चाहिए.
• fields पैरामीटर, एपीआई के रिस्पॉन्स को फ़िल्टर करता है, ताकि अनुरोध किए गए रिसॉर्स पार्ट में सिर्फ़ खास प्रॉपर्टी दिखे.

part पैरामीटर इस्तेमाल करने का तरीका

part पैरामीटर, किसी भी एपीआई अनुरोध के लिए ज़रूरी पैरामीटर होता है, जो किसी रिसॉर्स को हासिल करता है या दिखाता है. पैरामीटर, एक या उससे ज़्यादा टॉप लेवल (बिना नेस्ट किए गए) रिसॉर्स प्रॉपर्टी की पहचान करता है, जिन्हें एपीआई के रिस्पॉन्स में शामिल किया जाना चाहिए. उदाहरण के लिए, video संसाधन में ये हिस्से होते हैं:

• snippet
• contentDetails
• fileDetails
• player
• processingDetails
• recordingDetails
• statistics
• status
• suggestions
• topicDetails

ये सभी हिस्से ऐसे ऑब्जेक्ट हैं जिनमें नेस्ट की गई प्रॉपर्टी होती हैं. इन्हें मेटाडेटा फ़ील्ड के ग्रुप के तौर पर देखा जा सकता है जिन्हें एपीआई सर्वर वापस ला सकता है या शायद ऐक्सेस न कर पाए. इस तरह, part पैरामीटर के लिए आपको संसाधन के वे कॉम्पोनेंट चुनने होंगे जिनका इस्तेमाल आपका ऐप्लिकेशन असल में करता है. इस ज़रूरी शर्त के दो मकसद हैं:

• यह एपीआई सर्वर को उन मेटाडेटा फ़ील्ड को दोबारा पाने से रोकता है जिनका इस्तेमाल आपका ऐप्लिकेशन नहीं करता. इससे इंतज़ार का समय कम हो जाता है.
• यह आपके ऐप्लिकेशन के काम न करने वाले ग़ैर-ज़रूरी डेटा को कम करके (या हटाकर) बैंडविथ के इस्तेमाल को कम करता है.

समय के साथ, जैसे-जैसे संसाधन ज़्यादा होंगे, वैसे-वैसे ये फ़ायदे सिर्फ़ बढ़ते जाएंगे. इसकी वजह यह है कि आपका ऐप्लिकेशन, लागू की गई ऐसी नई प्रॉपर्टी के लिए अनुरोध नहीं करेगा जो काम नहीं करतीं.

fields पैरामीटर इस्तेमाल करने का तरीका

fields पैरामीटर, एपीआई के रिस्पॉन्स को फ़िल्टर करता है. इसमें सिर्फ़ part पैरामीटर की वैल्यू में बताए गए रिसॉर्स वाले हिस्से ही शामिल होते हैं. ऐसा इसलिए किया जाता है, ताकि रिस्पॉन्स में फ़ील्ड का सिर्फ़ चुनिंदा सेट शामिल हो. fields पैरामीटर की मदद से, नेस्ट की गई प्रॉपर्टी को एपीआई रिस्पॉन्स से हटाया जा सकता है. इससे बैंडविथ के इस्तेमाल को भी कम किया जा सकता है. (किसी रिस्पॉन्स से नेस्ट की गई प्रॉपर्टी को फ़िल्टर करने के लिए part पैरामीटर का इस्तेमाल नहीं किया जा सकता.)

ये नियम fields पैरामीटर वैल्यू के लिए इस्तेमाल किए जाने वाले सिंटैक्स के बारे में बताते हैं, जो आम तौर पर XPath सिंटैक्स पर आधारित होता है:

• एक से ज़्यादा फ़ील्ड चुनने के लिए, कॉमा लगाकर अलग की गई सूची (fields=a,b) का इस्तेमाल करें.
• सभी फ़ील्ड की पहचान करने के लिए, वाइल्डकार्ड के तौर पर तारे के निशान (fields=*) का इस्तेमाल करें.
• एपीआई के रिस्पॉन्स में शामिल की जाने वाली नेस्ट की गई प्रॉपर्टी के ग्रुप के बारे में बताने के लिए, ब्रैकेट (fields=a(b,c)) का इस्तेमाल करें.
• नेस्ट की गई प्रॉपर्टी की पहचान करने के लिए, फ़ॉरवर्ड स्लैश (fields=a/b) का इस्तेमाल करें.

ये नियम अक्सर एक ही एपीआई रिस्पॉन्स को पाने के लिए, कई अलग-अलग fields पैरामीटर वैल्यू की अनुमति देते हैं. उदाहरण के लिए, अगर आपको किसी प्लेलिस्ट में मौजूद हर आइटम की प्लेलिस्ट का आइटम आईडी, टाइटल, और उसकी पोज़िशन पता करनी है, तो इनमें से किसी भी वैल्यू का इस्तेमाल किया जा सकता है:

• fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
• fields=items(id,snippet/title,snippet/position)
• fields=items(id,snippet(title,position))

ध्यान दें: सभी क्वेरी पैरामीटर वैल्यू की तरह ही, fields पैरामीटर की वैल्यू को भी यूआरएल के हिसाब से कोड में बदला जाना चाहिए. इस दस्तावेज़ में दिए गए उदाहरणों में, कोड में बदलने के तरीके को शामिल नहीं किया गया है. इससे दस्तावेज़ को आसानी से पढ़ा जा सकता है.

आंशिक अनुरोधों के उदाहरण

यहां दिए गए उदाहरणों में बताया गया है कि part और fields पैरामीटर का इस्तेमाल करके, यह पक्का कैसे किया जा सकता है कि एपीआई से मिले जवाबों में सिर्फ़ वह डेटा शामिल हो जिसका इस्तेमाल आपके ऐप्लिकेशन करता है:

1. उदाहरण 1 में ऐसा वीडियो रिसॉर्स दिखाया गया है जिसके चार हिस्सों के साथ-साथ kind और etag प्रॉपर्टी भी शामिल हैं.
2. उदाहरण 2 ऐसा वीडियो रिसॉर्स दिखाता है जिसमें दो हिस्सों के साथ-साथ kind और etag प्रॉपर्टी भी शामिल होती हैं.
3. उदाहरण 3 ऐसा वीडियो रिसॉर्स दिखाता है जिसमें दो हिस्से शामिल हैं, लेकिन kind और etag प्रॉपर्टी शामिल नहीं हैं.
4. उदाहरण 4 ऐसा वीडियो रिसॉर्स दिखाता है जिसमें दो हिस्से शामिल हैं. हालांकि, इसमें kind और etag के साथ-साथ रिसॉर्स के snippet ऑब्जेक्ट में नेस्ट की गई कुछ प्रॉपर्टी शामिल नहीं हैं.

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,contentDetails,statistics,status

Description: This example retrieves a video resource and identifies several
             resource parts that should be included in the API response.

API response:

{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "contentDetails": {
    "duration": "PT15M51S",
    "aspectRatio": "RATIO_16_9"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   },
   "status": {
    "uploadStatus": "STATUS_PROCESSED",
    "privacyStatus": "PRIVACY_PUBLIC"
   }
  }
 ]
}

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics

Description: This example modifies the part parameter value so that the
             contentDetails and status properties are not included
             in the response.

API response:

{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics&fields=items(id,snippet,statistics)

Description: This example adds the fields parameter to remove all
             kind and etag properties from the API response.

API response:

{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics

Description: This example modifies the fields parameter from example 3
             so that in the API response, each video resource's snippet
             object only includes the channelId, title,
             and categoryId properties.

API response:

{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

परफ़ॉर्मेंस ऑप्टिमाइज़ करना

Accept-Encoding: gzip
User-Agent: my program (gzip)