रीयल-टाइम रिपोर्टिंग एपीआई - अनुमति देना

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

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

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

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

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

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

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

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

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

  1. ऐप्लिकेशन बनाने के बाद, उसे Google API (एपीआई) कंसोल का इस्तेमाल करके, रजिस्टर किया जाता है. इसके बाद, Google आपको क्लाइंट आईडी और क्लाइंट सीक्रेट जैसी जानकारी देगा. इस जानकारी की ज़रूरत आपको बाद में पड़ेगी.
  2. Google API (एपीआई) कंसोल में जाकर, Analytics API को चालू करें. (अगर एपीआई को '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 कंसोल में प्रोजेक्ट बनाने, एपीआई चालू करने, और क्रेडेंशियल बनाने के बारे में जानकारी देता है.

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

  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वां रीफ़्रेश टोकन, पहले जारी किए गए दूसरे टोकन को अमान्य कर देगा. इसी तरह, यह दूसरी प्रोसेस को भी अमान्य कर देगा.