Core Reporting API - ऑथराइज़ेशन

इस गाइड में बताया गया है कि कोई ऐप्लिकेशन, Core Reporting API के अनुरोधों की अनुमति कैसे देता है.

अनुमति देने वाले अनुरोध

उपयोगकर्ताओं को Google Analytics वेब साइट पर अपने खाते की जानकारी देखने के लिए, पहले अपने Google खातों में लॉग इन करना होगा. इसी तरह, जब उपयोगकर्ता पहली बार आपके ऐप्लिकेशन को ऐक्सेस करते हैं, तो उन्हें अपने डेटा को ऐक्सेस करने के लिए आपके ऐप्लिकेशन को अनुमति देनी होगी.

आपका ऐप्लिकेशन, Analytics API को जो भी अनुरोध भेजता है उसमें, अनुमति वाला टोकन शामिल होना चाहिए. इस टोकन से Google आपके ऐप्लिकेशन की पहचान भी करता है.

अनुमति देने के प्रोटोकॉल के बारे में जानकारी

अनुरोधों को अनुमति देने के लिए, आपके ऐप्लिकेशन में OAuth 2.0 का इस्तेमाल किया जाना चाहिए. अनुमति देने वाले दूसरे प्रोटोकॉल इस्तेमाल नहीं किए जा सकते. अगर आपका ऐप्लिकेशन Google से साइन इन करने की सुविधा इस्तेमाल करता है, तो अनुमति देने से जुड़े कुछ पहलुओं को Google आपके लिए खुद मैनेज करता है.

OAuth 2.0 से अनुरोधों को अनुमति देना

Analytics API को किए गए सभी अनुरोध की पुष्टि किसी ऐसे उपयोगकर्ता से की जानी चाहिए जिसकी पुष्टि हो चुकी हो.

OAuth 2.0 के लिए अनुमति देने की प्रक्रिया या "तरीका" अलग-अलग हो सकता है. यह इस बात पर निर्भर करता है कि ऐप्लिकेशन किस तरह का है. सभी तरह के ऐप्लिकेशन के लिए नीचे दी गई सामान्य प्रक्रिया लागू होती है:

  1. ऐप्लिकेशन बनाने के बाद, उसे Google API (एपीआई) कंसोल का इस्तेमाल करके, रजिस्टर किया जाता है. इसके बाद, Google आपको क्लाइंट आईडी और क्लाइंट सीक्रेट जैसी जानकारी देगा. इस जानकारी की ज़रूरत आपको बाद में पड़ेगी.
  2. Google API (एपीआई) कंसोल में Analytics एपीआई चालू करें. (अगर एपीआई को 'API कंसोल' की सूची में नहीं जोड़ा गया है, तो यह चरण छोड़ दें.)
  3. जब आपके ऐप्लिकेशन को उपयोगकर्ता के डेटा को ऐक्सेस करने की ज़रूरत होती है, तब वह Google से, डेटा के खास लिंक का अनुरोध करता है.
  4. Google, उपयोगकर्ता को सहमति वाली स्क्रीन दिखाता है, जिसमें उनसे आपके ऐप्लिकेशन को उनके कुछ डेटा को ऐक्सेस करने की अनुमति मांगी जाती है.
  5. अगर उपयोगकर्ता इसकी अनुमति दे देता है, तो Google आपके ऐप्लिकेशन को कुछ समय के लिए इस्तेमाल किए जा सकने वाला ऐक्सेस टोकन देता है.
  6. आपका ऐप्लिकेशन, ऐक्सेस टोकन से उपयोगकर्ता के डेटा को ऐक्सेस करने का अनुरोध करता है.
  7. अगर Google को पता चलता है कि आपका अनुरोध और टोकन मान्य है, तो वह आपके ऐप्लिकेशन को अनुरोध किए गए डेटा का ऐक्सेस दे देता है.

कुछ तरीकों में दूसरे चरण भी शामिल हो सकते हैं, जैसे कि रिफ़्रेश टोकन इस्तेमाल करके, नया ऐक्सेस टोकन पाना. अलग-अलग तरह के ऐप्लिकेशन के लिए डेटा ऐक्सेस करने के तरीकों के बारे में ज़्यादा जानकारी पाने के लिए, Google का OAuth 2.0 दस्तावेज़ पढ़ें.

यहां Analytics API के लिए OAuth 2.0 दायरे की जानकारी दी गई है:

स्कोप मतलब
https://www.googleapis.com/auth/analytics.readonly Analytics API के लिए रीड ओनली ऐक्सेस.

OAuth 2.0 का इस्तेमाल करके, डेटा ऐक्सेस करने का अनुरोध करने के लिए, आपके ऐप्लिकेशन को अनुरोध के तरीके की जानकारी देनी होगी. साथ ही, वह जानकारी भी देनी होगी जो आपको ऐप्लिकेशन रजिस्टर करते समय, Google से मिली थी, जैसे कि क्लाइंट आईडी और क्लाइंट सीक्रेट.

सलाह: Google API की क्लाइंट लाइब्रेरी आपके लिए अनुमति देने की कुछ प्रक्रियाएं खुद कर सकती है. ये लाइब्रेरी कई प्रोग्रामिंग भाषाओं के लिए उपलब्ध होती हैं. ज़्यादा जानकारी के लिए लाइब्रेरी और नमूनों वाला पेज देखें.

OAuth 2.0 के सामान्य फ़्लो

नीचे दिए गए, खास OAuth 2.0 फ़्लो के लिए, इस्तेमाल के सामान्य उदाहरण दिए गए हैं:

वेब सर्वर

यह फ़्लो किसी उपयोगकर्ता के Google Analytics डेटा के ऑटोमेटेड, ऑफ़लाइन या शेड्यूल किए गए ऐक्सेस के लिए अच्छा है.

उदाहरण:

  • उपयोगकर्ता डैशबोर्ड में Google Analytics का नया डेटा अपने-आप अपडेट होता है.

क्लाइंट-साइड

यह फ़्लो, उन ऐप्लिकेशन के लिए सबसे अच्छा है जब उपयोगकर्ता किसी ब्राउज़र में अपने Google Analytics डेटा को ऐक्सेस करने के लिए, सीधे ऐप्लिकेशन के साथ इंटरैक्ट करते हैं. इससे सर्वर-साइड की क्षमताओं की ज़रूरत नहीं पड़ती. हालांकि, इसकी मदद से ऑटोमेटेड, ऑफ़लाइन या शेड्यूल की गई रिपोर्टिंग को ठीक से काम नहीं किया जा सकता.

उदाहरण:

इंस्टॉल किए गए ऐप्लिकेशन

यह फ़्लो उन ऐप्लिकेशन के लिए है जिन्हें उपयोगकर्ता ने पैकेज के तौर पर उपलब्ध कराया है और इंस्टॉल किया है. इस फ़्लो के लिए, पुष्टि करने की प्रोसेस को पूरा करने के लिए ज़रूरी है कि ऐप्लिकेशन या उपयोगकर्ता के पास ब्राउज़र का ऐक्सेस हो.

उदाहरण:

  • PC या Mac पर डेस्कटॉप विजेट.
  • कॉन्टेंट मैनेजमेंट सिस्टम के लिए एक प्लगिन — वेब सर्वर या क्लाइंट-साइड की तुलना में इस फ़्लो का फ़ायदा यह है कि आपके ऐप्लिकेशन के लिए, एक ही एपीआई कंसोल प्रोजेक्ट का इस्तेमाल किया जा सकता है. इसकी मदद से, उपयोगकर्ताओं के लिए एक ही रिपोर्ट तैयार की जाती है और उन्हें आसानी से इंस्टॉल किया जा सकता है.

सेवा खाते

सेवा खाते, आपके खाते से Google Analytics डेटा के लिए ऑटोमेटेड, ऑफ़लाइन या शेड्यूल किए गए ऐक्सेस के लिए उपयोगी होते हैं. उदाहरण के लिए, अपने Google Analytics डेटा का लाइव डैशबोर्ड बनाना और उसे अन्य उपयोगकर्ताओं के साथ शेयर करना.

Analytics API का इस्तेमाल शुरू करने से पहले, सेटअप टूल इस्तेमाल करना होगा. यह आपको Google API Console में प्रोजेक्ट बनाने, एपीआई की सुविधा चालू करने, और क्रेडेंशियल बनाने के बारे में जानकारी देता है.

नया सेवा खाता सेट अप करने के लिए, ये काम करें:

  1. क्रेडेंशियल बनाएं > सेवा खाता कुंजी पर क्लिक करें.
  2. चुनें कि सेवा खाते की सार्वजनिक/निजी कुंजी को स्टैंडर्ड P12 फ़ाइल के तौर पर डाउनलोड करना है या ऐसी JSON फ़ाइल के तौर पर जिसे Google API क्लाइंट लाइब्रेरी से लोड किया जा सकता है.

आपके नए सार्वजनिक/निजी पासकोड को कंप्यूटर में बनाया और डाउनलोड किया जाता है. यह पासकोड की इकलौती कॉपी होती है. इसके सुरक्षित रूप से संग्रहित करने की ज़िम्मेदारी आपकी है.

समस्या हल करना

इन स्थितियों में अनुमति नहीं मिल पाती:

  • अगर आपके access_token की समयसीमा खत्म हो गई है या एपीआई के लिए गलत दायरे का इस्तेमाल किया जा रहा है, तो आपको 401 स्टेटस कोड मिलेगा.

  • अगर आधिकारिक उपयोगकर्ता के पास व्यू (प्रोफ़ाइल) का ऐक्सेस नहीं है, तो आपको एक 403 स्टेटस कोड मिलेगा. पक्का करें कि आप सही उपयोगकर्ता से जुड़े हैं और उसके पास वाकई में वह व्यू (प्रोफ़ाइल) है जिसे आपने चुना है.

OAuth 2.0 प्लेग्राउंड

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

अमान्य अनुमति

रीफ़्रेश टोकन का इस्तेमाल करने की कोशिश करने पर, आपको invalid_grant गड़बड़ी का मैसेज मिलता है:

किसी एक Google Analytics खाते को ऐक्सेस करने के लिए, ऐप्लिकेशन कई रीफ़्रेश टोकन का अनुरोध कर सकते हैं.

उदाहरण के लिए, अगर कोई उपयोगकर्ता कई मशीनों पर कोई ऐप्लिकेशन इंस्टॉल करके एक ही Google Analytics खाते को ऐक्सेस करना चाहता है, तो हर मशीन के लिए एक अलग टोकन की ज़रूरत होगी. जब रीफ़्रेश टोकन की संख्या तय सीमा से ज़्यादा हो जाती है, तब पुराने टोकन अमान्य हो जाते हैं. अगर ऐप्लिकेशन किसी अमान्य रीफ़्रेश टोकन का इस्तेमाल करने की कोशिश करता है, तो invalid_grant गड़बड़ी का जवाब मिलता है.

OAuth 2.0 क्लाइंट और Google Analytics खाते के हर यूनीक जोड़े के लिए, 25 रीफ़्रेश टोकन की सीमा तय है. अगर ऐप्लिकेशन एक ही क्लाइंट/खाते के पेयर के लिए, रीफ़्रेश टोकन का अनुरोध करता रहता है, तो 26वां टोकन जारी होने के बाद, पहले जारी किया गया पहला रीफ़्रेश टोकन अमान्य हो जाएगा. अनुरोध किया गया 27वां रीफ़्रेश टोकन, पहले जारी किए गए दूसरे टोकन को अमान्य कर देगा. यह क्रम इसी तरह के दूसरे टोकन को अमान्य करने की वजह से होगा.