इस दस्तावेज़ में बताया गया है कि टीवी, गेम कंसोल, और प्रिंटर जैसे डिवाइसों पर चलने वाले ऐप्लिकेशन की मदद से, YouTube Data API को ऐक्सेस करने के लिए, OAuth 2.0 की अनुमति को कैसे लागू किया जाता है. खास तौर पर, यह फ़्लो उन डिवाइसों के लिए डिज़ाइन किया गया है जिनके पास या तो ब्राउज़र का ऐक्सेस नहीं है या इनपुट देने के लिए सीमित सुविधाएं हैं.
OAuth 2.0 की मदद से, उपयोगकर्ता किसी ऐप्लिकेशन के साथ खास डेटा शेयर कर सकते हैं. हालांकि, इस दौरान उनके उपयोगकर्ता नाम, पासवर्ड, और अन्य जानकारी को निजी रखा जाता है. उदाहरण के लिए, Google Drive पर सेव की गई किसी फ़ाइल को चुनने की अनुमति पाने के लिए, कोई टीवी ऐप्लिकेशन OAuth 2.0 का इस्तेमाल कर सकता है.
इस फ़्लो का इस्तेमाल करने वाले ऐप्लिकेशन, अलग-अलग डिवाइसों में डिस्ट्रिब्यूट किए जाते हैं. इसलिए, यह माना जाता है कि ऐप्लिकेशन, गोपनीय ईमेल नहीं रख सकते. उपयोगकर्ता के पास, ऐप्लिकेशन के मौजूद रहने या बैकग्राउंड में चलने के दौरान, वे Google API को ऐक्सेस कर सकते हैं.
विकल्प
अगर Android, iOS, macOS, Linux या Windows (इसमें Universal Windows Platform शामिल है) जैसे किसी प्लैटफ़ॉर्म के लिए ऐप्लिकेशन लिखा जा रहा है, जिसके पास ब्राउज़र और सभी इनपुट सुविधाओं का ऐक्सेस है, तो मोबाइल और डेस्कटॉप ऐप्लिकेशन के लिए OAuth 2.0 फ़्लो का इस्तेमाल करें. (आपको इस फ़्लो का इस्तेमाल करना चाहिए, भले ही आपका ऐप्लिकेशन बिना ग्राफ़िकल इंटरफ़ेस वाला कमांड-लाइन टूल हो.)
अगर आपको सिर्फ़ उपयोगकर्ताओं के Google खाते से साइन इन करना है और उपयोगकर्ता की प्रोफ़ाइल की बुनियादी जानकारी पाने के लिए, JWT आईडी टोकन का इस्तेमाल करना है, तो टीवी और सीमित इनपुट डिवाइसों पर साइन इन करना लेख पढ़ें.
ज़रूरी शर्तें
अपने प्रोजेक्ट के लिए एपीआई चालू करना
Google API को कॉल करने वाले किसी भी ऐप्लिकेशन को, API Consoleमें उन एपीआई को चालू करना होगा.
अपने प्रोजेक्ट के लिए एपीआई चालू करने के लिए:
- Google API Consoleमें Open the API Library .
- If prompted, select a project, or create a new one.
- YouTube Data API को ढूंढने और चालू करने के लिए, लाइब्रेरी पेज का इस्तेमाल करें. ऐसे कोई दूसरे एपीआई ढूंढें जिनका इस्तेमाल आपका ऐप्लिकेशन करेगा और उन्हें भी चालू करें.
अनुमति देने वाले क्रेडेंशियल बनाएं
Google API को ऐक्सेस करने के लिए OAuth 2.0 का इस्तेमाल करने वाले किसी भी ऐप्लिकेशन में, ऐसे ऑथराइज़ेशन क्रेडेंशियल होने चाहिए जिनसे Google के OAuth 2.0 सर्वर पर ऐप्लिकेशन की पहचान की जा सके. अपने प्रोजेक्ट के लिए क्रेडेंशियल बनाने का तरीका यहां बताया गया है. इसके बाद, आपके ऐप्लिकेशन उन एपीआई को ऐक्सेस करने के लिए क्रेडेंशियल का इस्तेमाल कर सकते हैं जिन्हें आपने उस प्रोजेक्ट के लिए चालू किया है.
- Go to the Credentials page.
- क्रेडेंशियल बनाएं > OAuth क्लाइंट आईडी पर क्लिक करें.
- टीवी और सीमित इनपुट डिवाइस ऐप्लिकेशन टाइप चुनें.
- अपने OAuth 2.0 क्लाइंट को कोई नाम दें और बनाएं पर क्लिक करें.
ऐक्सेस के दायरों की पहचान करना
स्कोप की सुविधा का इस्तेमाल करके आपका ऐप्लिकेशन, सिर्फ़ उन संसाधनों का ऐक्सेस मांग सकता है जिनकी उसे ज़रूरत है. साथ ही, उपयोगकर्ता आपके ऐप्लिकेशन को दिए गए ऐक्सेस की सीमा को कंट्रोल कर सकते हैं. इसलिए, अनुरोध किए गए दायरों की संख्या और उपयोगकर्ता की सहमति लेने की संभावना, अलग-अलग हो सकती है.
हमारा सुझाव है कि OAuth 2.0 की अनुमति देने की सुविधा लागू करने से पहले, आप उन दायरों का पता लगा लें जिन्हें ऐक्सेस करने के लिए आपके ऐप्लिकेशन को अनुमति की ज़रूरत होगी.
YouTube Data API v3 इन दायरों का इस्तेमाल करता है:
बंदूक पर लगने वाली दूरबीन | |
---|---|
https://www.googleapis.com/auth/youtube | अपना YouTube खाता मैनेज करें |
https://www.googleapis.com/auth/youtube.channel-memberships.creator | अपने चैनल के मौजूदा सक्रिय सदस्यों की सूची और उनका मौजूदा लेवल देखें. यह भी देखें कि वे चैनल के सदस्य कब बने |
https://www.googleapis.com/auth/youtube.force-ssl | अपने YouTube वीडियो की रेटिंग, टिप्पणियां और कैप्शन देखें, उनमें बदलाव करें और उन्हें हमेशा के लिए मिटाएं |
https://www.googleapis.com/auth/youtube.readonly | अपना YouTube खाता देखें |
https://www.googleapis.com/auth/youtube.upload | अपने YouTube वीडियो मैनेज करें |
https://www.googleapis.com/auth/youtubepartner | YouTube पर अपनी परिसंपत्ति तथा संबंधित सामग्री देखें व प्रबंधित करें |
https://www.googleapis.com/auth/youtubepartner-channel-audit | किसी YouTube भागीदार की ऑडिट प्रक्रिया के दौरान उससे प्रासंगिक अपने YouTube चैनल की निजी जानकारी देखें |
इंस्टॉल किए गए ऐप्लिकेशन या डिवाइसों के लिए, अनुमति वाले दायरे की सूची देखें.
OAuth 2.0 ऐक्सेस टोकन पाना
भले ही आपका ऐप्लिकेशन सीमित इनपुट क्षमताओं वाले डिवाइस पर चलता है, लेकिन इस ऑथराइज़ेशन फ़्लो को पूरा करने के लिए, उपयोगकर्ताओं के पास बेहतर इनपुट क्षमताओं वाले डिवाइस का अलग से ऐक्सेस होना चाहिए. फ़्लो में ये चरण होते हैं:
- आपका ऐप्लिकेशन, Google के अनुमति देने वाले सर्वर को एक अनुरोध भेजता है. इससे उन दायरों की पहचान होती है जिन्हें आपका ऐप्लिकेशन ऐक्सेस करने की अनुमति मांगेगा.
- इसके बाद, सर्वर कई तरह की जानकारी देता है, जिसका इस्तेमाल आगे के चरणों में किया जाता है. जैसे, डिवाइस कोड और उपयोगकर्ता कोड.
- आपको वह जानकारी दिखती है जिसे उपयोगकर्ता, आपके ऐप्लिकेशन को अनुमति देने के लिए किसी दूसरे डिवाइस पर डाल सकता है.
- आपका ऐप्लिकेशन, Google के ऑथराइज़ेशन सर्वर की पोलिंग शुरू करता है, ताकि यह पता लगाया जा सके कि उपयोगकर्ता ने आपके ऐप्लिकेशन को अनुमति दी है या नहीं.
- उपयोगकर्ता बेहतर इनपुट क्षमताओं वाले डिवाइस पर स्विच करता है, वेब ब्राउज़र लॉन्च करता है, तीसरे चरण में दिखाए गए यूआरएल पर जाता है, और तीसरे चरण में दिखाया गया कोड डालता है. इसके बाद, उपयोगकर्ता आपके ऐप्लिकेशन को ऐक्सेस दे सकता है (या अस्वीकार कर सकता है).
- पोलिंग के अनुरोध के अगले जवाब में वे टोकन शामिल होते हैं जिनकी ज़रूरत आपके ऐप्लिकेशन को, उपयोगकर्ता की ओर से अनुरोधों को अनुमति देने के लिए होती है. (अगर उपयोगकर्ता ने आपके ऐप्लिकेशन को ऐक्सेस करने से मना कर दिया है, तो रिस्पॉन्स में टोकन शामिल नहीं होते.)
नीचे दी गई इमेज में यह प्रोसेस दिखाई गई है:
नीचे दिए गए सेक्शन में, इन चरणों के बारे में विस्तार से बताया गया है. डिवाइसों में इस्तेमाल की जा सकने वाली क्षमताओं और रनटाइम एनवायरमेंट की अलग-अलग रेंज को ध्यान में रखते हुए, इस दस्तावेज़ में दिखाए गए उदाहरण curl
कमांड लाइन सुविधा का इस्तेमाल करते हैं. इन उदाहरणों को अलग-अलग भाषाओं और रनटाइम में पोर्ट करना आसान होना चाहिए.
पहला चरण: डिवाइस और उपयोगकर्ता कोड का अनुरोध करना
इस चरण में, आपका डिवाइस https://oauth2.googleapis.com/device/code
पर मौजूद Google के अनुमति देने वाले सर्वर को एक एचटीटीपी पोस्ट अनुरोध भेजता है. यह आपके ऐप्लिकेशन और उन ऐक्सेस दायरों की पहचान करता है जिन्हें आपका ऐप्लिकेशन, उपयोगकर्ता की ओर से ऐक्सेस करना चाहता है.
आपको device_authorization_endpoint
की मेटाडेटा वैल्यू का इस्तेमाल करके, खोज से जुड़े दस्तावेज़ से इस यूआरएल को वापस पाना होगा. नीचे दिए गए एचटीटीपी अनुरोध के पैरामीटर शामिल करें:
पैरामीटर | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
ज़रूरी
आपके ऐप्लिकेशन का क्लाइंट आईडी. यह वैल्यू, आपको API Console Credentials pageमें मिलेगी. |
||||||||||||||||
scope |
ज़रूरी
दायरों की स्पेस-डीलिमिटेड सूची, जो उन संसाधनों की पहचान करती है जिन्हें आपका ऐप्लिकेशन, उपयोगकर्ता की ओर से ऐक्सेस कर सकता है. इन वैल्यू से उस स्क्रीन के बारे में पता चलता है जो Google, उपयोगकर्ता को दिखाता है. इंस्टॉल किए गए ऐप्लिकेशन या डिवाइसों के लिए, अनुमति वाले दायरे की सूची देखें. स्कोप की सुविधा का इस्तेमाल करके आपका ऐप्लिकेशन, सिर्फ़ उन संसाधनों का ऐक्सेस मांग सकता है जिनकी उसे ज़रूरत है. साथ ही, उपयोगकर्ता आपके ऐप्लिकेशन को दिए गए ऐक्सेस के लेवल को कंट्रोल कर सकते हैं. इसलिए, अनुरोध किए गए दायरों की संख्या और उपयोगकर्ता की सहमति पाने की संभावना, दोनों में बिलकुल उलट होता है. YouTube Data API v3 इन दायरों का इस्तेमाल करता है:
OAuth 2.0 एपीआई के दायरे दस्तावेज़ में, उन दायरों की पूरी सूची मिलती है जिनका इस्तेमाल Google API को ऐक्सेस करने के लिए किया जा सकता है. |
उदाहरण
नीचे दिए गए स्निपेट में, अनुरोध का एक सैंपल दिखाया गया है:
POST /device/code HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl
इस उदाहरण में, एक जैसे अनुरोध भेजने के लिए curl
कमांड दिखाया गया है:
curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl" \ https://oauth2.googleapis.com/device/code
दूसरा चरण: ऑथराइज़ेशन सर्वर के रिस्पॉन्स को मैनेज करना
ऑथराइज़ेशन सर्वर, इनमें से कोई एक रिस्पॉन्स देगा:
सफलता का रिस्पॉन्स
अगर अनुरोध मान्य है, तो आपका जवाब एक JSON ऑब्जेक्ट होगा, जिसमें ये प्रॉपर्टी शामिल होंगी:
प्रॉपर्टी | |
---|---|
device_code |
यह वह वैल्यू होती है जिसे Google खास तौर पर, उस डिवाइस की पहचान करने के लिए असाइन करता है जिस पर ऐप्लिकेशन चलाने की अनुमति पाने का अनुरोध किया जाता है. उपयोगकर्ता बेहतर इनपुट क्षमताओं वाले किसी दूसरे डिवाइस से उस डिवाइस को अनुमति देगा. उदाहरण के लिए, कोई उपयोगकर्ता टीवी पर चल रहे किसी ऐप्लिकेशन को अनुमति देने के लिए, लैपटॉप या मोबाइल फ़ोन का इस्तेमाल कर सकता है. इस मामले में, device_code , टीवी की पहचान करता है.
इस कोड की मदद से, ऐप्लिकेशन चलाने वाला डिवाइस सुरक्षित तरीके से यह तय करता है कि उपयोगकर्ता ने ऐक्सेस दिया है या नहीं. |
expires_in |
device_code और user_code मान्य होने की अवधि (सेकंड में). अगर इस दौरान उपयोगकर्ता, अनुमति देने का फ़्लो पूरा नहीं करता और आपका डिवाइस, उपयोगकर्ता के फ़ैसले की जानकारी पाने के लिए पोल नहीं करता, तो आपको पहले चरण से इस प्रोसेस को फिर से शुरू करना पड़ सकता है. |
interval |
पोलिंग के अनुरोध के बीच में डिवाइस को लगने वाला वह समय (सेकंड में). उदाहरण के लिए, अगर वैल्यू 5 है, तो आपके डिवाइस को हर पांच सेकंड में Google के ऑथराइज़ेशन सर्वर को पोलिंग अनुरोध भेजना चाहिए. ज़्यादा जानकारी के लिए,
तीसरा चरण देखें. |
user_code |
एक केस-सेंसिटिव वैल्यू, जो Google को उन दायरों की जानकारी देती है जिनके ऐक्सेस का अनुरोध ऐप्लिकेशन कर रहा है. आपका यूज़र इंटरफ़ेस, उपयोगकर्ता को इस वैल्यू को किसी ऐसे डिवाइस पर डालने का निर्देश देगा जिसमें बेहतर इनपुट हो. इसके बाद, उपयोगकर्ता को आपके ऐप्लिकेशन का ऐक्सेस देने का अनुरोध करते समय, Google सही दायरे को दिखाने के लिए इस वैल्यू का इस्तेमाल करता है. |
verification_url |
वह यूआरएल जिस पर उपयोगकर्ता को किसी दूसरे डिवाइस पर नेविगेट करके, user_code डालना होगा और आपके ऐप्लिकेशन का ऐक्सेस देना होगा या अनुमति नहीं देनी होगी. आपके यूज़र इंटरफ़ेस पर भी यह वैल्यू दिखेगी. |
नीचे दिया गया स्निपेट एक सैंपल रिस्पॉन्स दिखाता है:
{ "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8", "user_code": "GQVQ-JKEC", "verification_url": "https://www.google.com/device", "expires_in": 1800, "interval": 5 }
कोटे से ज़्यादा अनुरोध किया गया
अगर डिवाइस के कोड के अनुरोध, आपके क्लाइंट आईडी से जुड़े कोटा को पार कर चुके हैं, तो आपको 403 रिस्पॉन्स मिलेगा, जिसमें यह गड़बड़ी होगी:
{ "error_code": "rate_limit_exceeded" }
ऐसे मामले में, अनुरोधों की दर कम करने के लिए बैकऑफ़ रणनीति का इस्तेमाल करें.
तीसरा चरण: उपयोगकर्ता कोड दिखाना
दूसरे चरण में मिले verification_url
और user_code
उपयोगकर्ता को दिखाएं. दोनों वैल्यू में US-ASCII वर्ण सेट से कोई भी प्रिंट किया जा सकने वाला वर्ण हो सकता है. आपकी ओर से उपयोगकर्ता को दिखाए जाने वाले कॉन्टेंट को उपयोगकर्ता को किसी अलग डिवाइस पर verification_url
पर जाने और user_code
डालने के लिए निर्देश देना चाहिए.
नीचे दिए गए नियमों को ध्यान में रखते हुए अपना यूज़र इंटरफ़ेस (यूआई) डिज़ाइन करें:
user_code
user_code
को ऐसे फ़ील्ड में दिखाना ज़रूरी है जिसमें 15 'W' साइज़ वाले वर्ण हैंडल किए जा सकें. दूसरे शब्दों में, अगरWWWWWWWWWWWWWWW
कोड को सही तरीके से दिखाया जा सकता है, तो आपका यूज़र इंटरफ़ेस (यूआई) मान्य है. हमारा सुझाव है कि आप यूज़र इंटरफ़ेस (यूआई) मेंuser_code
के दिखने के तरीके की जांच करते समय, इस स्ट्रिंग वैल्यू का इस्तेमाल करें.user_code
केस-सेंसिटिव (बड़े और छोटे अक्षरों में अंतर) होता है और इसमें किसी भी तरह का बदलाव नहीं किया जाना चाहिए. जैसे, केस बदलना या फ़ॉर्मैटिंग वाले दूसरे वर्ण शामिल करना.
verification_url
- जिस स्पेस में
verification_url
दिखाना है वह इतनी चौड़ी होनी चाहिए कि उसमें 40 वर्णों वाली यूआरएल स्ट्रिंग को मैनेज किया जा सके. - आपको
verification_url
में किसी भी तरह का बदलाव नहीं करना चाहिए. हालांकि, विकल्प दिखाने के लिए स्कीम को हटाना ज़रूरी है. अगर आपको डिसप्ले की वजहों से यूआरएल से स्कीम (जैसे किhttps://
) को हटाना है, तो पक्का करें कि आपका ऐप्लिकेशनhttp
औरhttps
, दोनों वैरिएंट मैनेज कर सकता हो.
- जिस स्पेस में
चौथा चरण: पोल Google के ऑथराइज़ेशन सर्वर की मदद से पुष्टि करने की सुविधा
उपयोगकर्ता, verification_url
पर जाने और ऐक्सेस देने (या अस्वीकार) करने के लिए एक अलग डिवाइस का इस्तेमाल करेगा. इसलिए, जब उपयोगकर्ता ऐक्सेस के अनुरोध का जवाब देता है, तो अनुरोध किए गए डिवाइस को इसकी सूचना अपने-आप नहीं मिलती. इसी वजह से, अनुरोध करने वाले डिवाइस को Google के अनुमति देने वाले सर्वर की पोलिंग करनी होगी, ताकि यह तय किया जा सके कि उपयोगकर्ता ने अनुरोध का जवाब कब दिया है.
अनुरोध करने वाले डिवाइस को तब तक पोलिंग के अनुरोध भेजना जारी रखना चाहिए, जब तक कि उसे इस तरह का जवाब न मिल जाए कि उपयोगकर्ता ने ऐक्सेस के अनुरोध का जवाब दे दिया है.
इसके अलावा, जब तक
दूसरे चरण में मिले device_code
और user_code
की समयसीमा खत्म नहीं हो जाती, तब तक उसे पोलिंग के अनुरोध भेजना जारी रखना चाहिए. दूसरे चरण में दिया गया interval
, एक अनुरोध के बाद दूसरा अनुरोध मिलने तक इंतज़ार करने में लगने वाले समय की जानकारी देता है. यह जानकारी सेकंड में दी जाती है.
पोल के एंडपॉइंट का यूआरएल https://oauth2.googleapis.com/token
है. पोल कराने के अनुरोध में ये पैरामीटर शामिल होते हैं:
पैरामीटर | |
---|---|
client_id |
आपके ऐप्लिकेशन का क्लाइंट आईडी. यह वैल्यू, आपको API Console Credentials pageमें मिलेगी. |
client_secret |
दिए गए client_id के लिए क्लाइंट सीक्रेट. यह वैल्यू, आपको
API Console
Credentials pageमें मिलेगी. |
device_code |
ऑथराइज़ेशन सर्वर से मिला device_code ,
दूसरे चरण में दिखाया गया. |
grant_type |
इस वैल्यू को urn:ietf:params:oauth:grant-type:device_code पर सेट करें. |
उदाहरण
नीचे दिए गए स्निपेट में, अनुरोध का एक सैंपल दिखाया गया है:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=client_id& client_secret=client_secret& device_code=device_code& grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code
इस उदाहरण में, एक जैसे अनुरोध भेजने के लिए curl
कमांड दिखाया गया है:
curl -d "client_id=client_id&client_secret=client_secret& \ device_code=device_code& \ grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \ -H "Content-Type: application/x-www-form-urlencoded" \ https://oauth2.googleapis.com/token
पांचवां चरण: उपयोगकर्ता, ऐक्सेस के अनुरोध का जवाब देता है
नीचे दी गई इमेज में, उस पेज से मिलता-जुलता पेज दिखाया गया है जो उपयोगकर्ताओं को तब दिखता है, जब वे उस verification_url
पर जाते हैं जिसे आपने तीसरे चरण में दिखाया था:
अगर user_code
को डालने और पहले से लॉग इन न करके, Google में लॉग इन करने के बाद, उपयोगकर्ता को सहमति वाली स्क्रीन दिखती है, तो यह स्क्रीन पर दिखेगी:
छठा चरण: पोलिंग के अनुरोधों के जवाब मैनेज करना
अनुमति देने वाला Google का सर्वर, पोल के हर अनुरोध का जवाब देने के लिए, इनमें से कोई एक जवाब देता है:
ऐक्सेस दिया गया
अगर उपयोगकर्ता ने डिवाइस का ऐक्सेस दिया है (सहमति स्क्रीन पर Allow
पर क्लिक करके),
तो रिस्पॉन्स में ऐक्सेस टोकन और रीफ़्रेश टोकन शामिल होता है. टोकन, आपके डिवाइस को उपयोगकर्ता की ओर से
Google API ऐक्सेस करने की सुविधा देते हैं. (रिस्पॉन्स में शामिल scope
प्रॉपर्टी से यह तय होता है कि डिवाइस किन एपीआई
को ऐक्सेस कर सकता है.)
इस मामले में, एपीआई से मिले रिस्पॉन्स में ये फ़ील्ड शामिल होते हैं:
फ़ील्ड | |
---|---|
access_token |
वह टोकन जो आपका ऐप्लिकेशन, Google API अनुरोध को अनुमति देने के लिए भेजता है. |
expires_in |
ऐक्सेस टोकन की बची हुई अवधि कुछ सेकंड में. |
refresh_token |
ऐसा टोकन जिसका इस्तेमाल करके, नया ऐक्सेस टोकन पाया जा सकता है. रीफ़्रेश टोकन तब तक मान्य रहते हैं, जब तक उपयोगकर्ता ऐक्सेस रद्द नहीं कर देता. ध्यान दें कि डिवाइसों के लिए रीफ़्रेश टोकन हमेशा दिखाए जाते हैं. |
scope |
access_token के दिए ऐक्सेस के दायरे, स्पेस-डीलिमिटेड और केस-सेंसिटिव स्ट्रिंग की सूची के तौर पर दिखते हैं. |
token_type |
टोकन टाइप किया गया. फ़िलहाल, इस फ़ील्ड की वैल्यू हमेशा
Bearer पर सेट होती है. |
नीचे दिया गया स्निपेट एक सैंपल रिस्पॉन्स दिखाता है:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email", "token_type": "Bearer", "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
ऐक्सेस टोकन की समयसीमा सीमित होती है. अगर आपके ऐप्लिकेशन को लंबे समय तक किसी एपीआई के ऐक्सेस की ज़रूरत है, तो वह रीफ़्रेश टोकन का इस्तेमाल करके, नया ऐक्सेस टोकन पा सकता है. अगर आपके ऐप्लिकेशन को इस तरह के ऐक्सेस की ज़रूरत है, तो उसे रीफ़्रेश टोकन को बाद में इस्तेमाल करने के लिए सेव करना चाहिए.
ऐक्सेस करने की मंज़ूरी नहीं मिली
अगर उपयोगकर्ता डिवाइस का ऐक्सेस नहीं देता है, तो सर्वर रिस्पॉन्स में एक
403
एचटीटीपी रिस्पॉन्स स्टेटस कोड (Forbidden
) होता है. रिस्पॉन्स में यह गड़बड़ी
शामिल होती है:
{ "error": "access_denied", "error_description": "Forbidden" }
अनुमति मिलना बाकी है
अगर उपयोगकर्ता ने अभी तक ऑथराइज़ेशन फ़्लो पूरा नहीं किया है, तो सर्वर एक
428
एचटीटीपी रिस्पॉन्स स्टेटस कोड (Precondition Required
) दिखाता है. रिस्पॉन्स में यह गड़बड़ी
शामिल होती है:
{ "error": "authorization_pending", "error_description": "Precondition Required" }
बहुत जल्दी-जल्दी पोल किया जा रहा है
अगर डिवाइस बार-बार पोलिंग के अनुरोध भेजता है, तो सर्वर एक 403
एचटीटीपी रिस्पॉन्स स्टेटस कोड (Forbidden
) दिखाता है. रिस्पॉन्स में यह गड़बड़ी
शामिल होती है:
{ "error": "slow_down", "error_description": "Forbidden" }
दूसरी गड़बड़ियां
अगर पोलिंग अनुरोध में सभी ज़रूरी पैरामीटर मौजूद नहीं हैं या पैरामीटर की वैल्यू गलत है, तो भी ऑथराइज़ेशन सर्वर गड़बड़ियां दिखाता है. आम तौर पर, इन अनुरोधों में 400
(Bad Request
) या 401
(Unauthorized
) एचटीटीपी रिस्पॉन्स स्टेटस कोड होता है. इनमें ये गड़बड़ियां शामिल हैं:
गड़बड़ी | एचटीटीपी स्टेटस कोड | ब्यौरा |
---|---|---|
admin_policy_enforced |
400 |
उसके Google Workspace एडमिन की नीतियों की वजह से, Google खाता, एक या एक से ज़्यादा दायरों के लिए अनुरोध करने की अनुमति नहीं दे सकता. Google Workspace एडमिन का सहायता लेख पढ़ें, यह कंट्रोल करना कि तीसरे पक्ष और आपके डोमेन के कौनसे ऐप्लिकेशन, Google Workspace के डेटा को ऐक्सेस कर सकते हैं. इससे आपको यह जानने में मदद मिलेगी कि जब तक आपके OAuth क्लाइंट आईडी को साफ़ तौर पर ऐक्सेस नहीं दिया जाता, तब तक एडमिन किन दायरों के ऐक्सेस पर पाबंदी लगा सकता है. |
invalid_client |
401 |
OAuth क्लाइंट नहीं मिला. उदाहरण के लिए, यह गड़बड़ी तब होती है, जब
OAuth क्लाइंट का टाइप गलत है. पक्का करें कि क्लाइंट आईडी के लिए ऐप्लिकेशन टाइप, टीवी और सीमित इनपुट डिवाइस पर सेट हो. |
invalid_grant |
400 |
code पैरामीटर की वैल्यू अमान्य है, पहले से ही दावा किया जा चुका है या इसे पार्स नहीं किया जा सकता. |
unsupported_grant_type |
400 |
grant_type पैरामीटर की वैल्यू अमान्य है. |
org_internal |
403 |
अनुरोध में दिया गया OAuth क्लाइंट आईडी, एक ऐसे प्रोजेक्ट का हिस्सा है जो किसी खास Google Cloud संगठन में Google खातों का ऐक्सेस सीमित करता है. अपने OAuth ऐप्लिकेशन के लिए, उपयोगकर्ता के टाइप के कॉन्फ़िगरेशन की पुष्टि करें. |
Calling Google API
आपके ऐप्लिकेशन को ऐक्सेस टोकन मिल जाने के बाद, किसी उपयोगकर्ता खाते की ओर से Google API को कॉल करने के लिए, टोकन का इस्तेमाल किया जा सकता है. हालांकि, इसके लिए ज़रूरी है कि एपीआई के लिए ज़रूरी ऐक्सेस के दायरे दिए गए हों. ऐसा करने के लिए, एपीआई को किए गए अनुरोध में ऐक्सेस टोकन शामिल करें. इसके लिए, access_token
क्वेरी पैरामीटर या Authorization
एचटीटीपी हेडर Bearer
वैल्यू शामिल करें. जब मुमकिन हो, तब एचटीटीपी हेडर को प्राथमिकता दी जानी चाहिए, क्योंकि सर्वर लॉग में क्वेरी स्ट्रिंग अक्सर दिखती हैं. ज़्यादातर मामलों में,
Google API पर अपने कॉल सेट अप करने के लिए, क्लाइंट लाइब्रेरी का इस्तेमाल किया जा सकता है. उदाहरण के लिए,
YouTube Live Streaming API को कॉल करते समय.
ध्यान दें कि YouTube Live Streaming API, सेवा खाते के फ़्लो के साथ काम नहीं करता. सेवा खाते को YouTube खाते से लिंक करने का कोई तरीका नहीं है. इसलिए, इस फ़्लो का इस्तेमाल करके अनुरोधों को अनुमति देने की कोशिश करने पर, NoLinkedYouTubeAccount
गड़बड़ी जनरेट होगी.
OAuth 2.0 प्लेग्राउंड में, सभी Google API को आज़माया जा सकता है और उनके स्कोप देखे जा सकते हैं.
एचटीटीपी जीईटी के उदाहरण
Authorization: Bearer
एचटीटीपी हेडर का इस्तेमाल करके,
liveBroadcasts.list
एंडपॉइंट (YouTube Live Streaming API)
को कॉल करने पर ऐसा दिख सकता है. ध्यान दें कि आपको अपना ऐक्सेस टोकन बताना होगा:
GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
यहां access_token
क्वेरी स्ट्रिंग पैरामीटर का इस्तेमाल करके, पुष्टि किए गए उपयोगकर्ता के लिए उसी एपीआई को कॉल किया गया है:
GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
curl
के उदाहरण
curl
कमांड-लाइन ऐप्लिकेशन का इस्तेमाल करके, इन कमांड की जांच की जा सकती है. यहां एक उदाहरण दिया गया है, जिसमें एचटीटीपी हेडर विकल्प का इस्तेमाल किया जाता है (इसका सुझाव दिया जाता है):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true
इसके अलावा, क्वेरी स्ट्रिंग पैरामीटर विकल्प:
curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
ऐक्सेस टोकन को रीफ़्रेश करना
ऐक्सेस टोकन, समय-समय पर खत्म हो जाते हैं और मिलते-जुलते एपीआई अनुरोध के लिए, अमान्य क्रेडेंशियल बन जाते हैं. अगर आपने टोकन से जुड़े स्कोप के लिए ऑफ़लाइन ऐक्सेस का अनुरोध किया है, तो उपयोगकर्ता से अनुमति मांगे बिना (उपयोगकर्ता के मौजूद न होने पर भी) ऐक्सेस टोकन को रीफ़्रेश किया जा सकता है.
किसी ऐक्सेस टोकन को रीफ़्रेश करने के लिए, आपका ऐप्लिकेशन Google के ऑथराइज़ेशन सर्वर (https://oauth2.googleapis.com/token
) को एचटीटीपीएस POST
का अनुरोध भेजता है. इस अनुरोध में ये पैरामीटर शामिल होते हैं:
फ़ील्ड | |
---|---|
client_id |
API Consoleसे मिला क्लाइंट आईडी. |
client_secret |
API Consoleसे मिला क्लाइंट सीक्रेट. |
grant_type |
जैसा कि OAuth 2.0 की खास बातों में बताया गया है, इस फ़ील्ड की वैल्यू refresh_token पर सेट होनी चाहिए. |
refresh_token |
ऑथराइज़ेशन कोड के एक्सचेंज से मिला रीफ़्रेश टोकन. |
नीचे दिए गए स्निपेट में, अनुरोध का एक सैंपल दिखाया गया है:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=your_client_id& client_secret=your_client_secret& refresh_token=refresh_token& grant_type=refresh_token
जब तक उपयोगकर्ता ने ऐप्लिकेशन को दिया गया ऐक्सेस रद्द नहीं किया, तब तक टोकन सर्वर, JSON ऑब्जेक्ट दिखाता है. इस ऑब्जेक्ट में नया ऐक्सेस टोकन होता है. नीचे दिया गया स्निपेट एक सैंपल रिस्पॉन्स दिखाता है:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "scope": "https://www.googleapis.com/auth/drive.metadata.readonly", "token_type": "Bearer" }
ध्यान दें कि जारी किए जाने वाले रीफ़्रेश टोकन की संख्या सीमित है; हर क्लाइंट/उपयोगकर्ता के कॉम्बिनेशन के लिए एक सीमा और सभी क्लाइंट के लिए हर उपयोगकर्ता के लिए दूसरी सीमा. रीफ़्रेश टोकन को लंबे समय तक इस्तेमाल करने के लिए सेव करके रखना चाहिए. साथ ही, जब तक ये मान्य रहेंगे, इनका इस्तेमाल जारी रखना चाहिए. अगर आपका ऐप्लिकेशन बहुत ज़्यादा रीफ़्रेश टोकन का अनुरोध करता है, तो वह इन सीमाओं का पालन कर सकता है. इस स्थिति में, पुराने रीफ़्रेश टोकन काम करना बंद कर देंगे.
टोकन निरस्त करना
कुछ मामलों में, हो सकता है कि उपयोगकर्ता किसी ऐप्लिकेशन को दिया गया ऐक्सेस वापस लेना चाहें. उपयोगकर्ता, खाता सेटिंग में जाकर ऐक्सेस रद्द कर सकता है. ज़्यादा जानकारी के लिए, तीसरे पक्ष की उन साइटों और ऐप्लिकेशन के पास मौजूद, साइट या ऐप्लिकेशन के ऐक्सेस को हटाएं सेक्शन हटाएं जिनके पास आपके खाते का ऐक्सेस है सहायता दस्तावेज़ देखें.
किसी ऐप्लिकेशन को दी गई ऐक्सेस को प्रोग्राम के हिसाब से रद्द करना भी संभव है. प्रोग्राम के हिसाब से प्रोसेस को रद्द करना तब ज़रूरी होता है, जब कोई उपयोगकर्ता सदस्यता छोड़ता है, किसी ऐप्लिकेशन को हटा देता है या किसी ऐप्लिकेशन के लिए ज़रूरी एपीआई संसाधनों में काफ़ी बदलाव करता है. दूसरे शब्दों में, ऐप्लिकेशन को हटाने की प्रोसेस के एक हिस्से में एपीआई अनुरोध शामिल हो सकता है. इससे यह पक्का किया जाता है कि ऐप्लिकेशन को पहले दी गई अनुमतियां हटा दी गई हैं.
किसी टोकन को प्रोग्राम के हिसाब से रद्द करने के लिए, आपका ऐप्लिकेशन https://oauth2.googleapis.com/revoke
को अनुरोध करता है और टोकन को पैरामीटर के तौर पर शामिल करता है:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \ https://oauth2.googleapis.com/revoke?token={token}
टोकन, ऐक्सेस टोकन या रीफ़्रेश टोकन हो सकता है. अगर टोकन एक ऐक्सेस टोकन है और उसमें उससे जुड़ा रीफ़्रेश टोकन मौजूद है, तो रीफ़्रेश टोकन भी रद्द कर दिया जाएगा.
अगर सहमति रद्द हो जाती है, तो रिस्पॉन्स का एचटीटीपी स्टेटस कोड
200
होता है. गड़बड़ी की स्थितियों के लिए, गड़बड़ी के कोड के साथ एचटीटीपी स्टेटस कोड 400
दिखाया जाता है.
अनुमति वाले दायरे
डिवाइसों के लिए, OAuth 2.0 फ़्लो सिर्फ़ इन दायरों के लिए काम करता है:
OpenID Connect, Google साइन-इन
email
openid
profile
Drive API
https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.file
YouTube API
https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.readonly