सीधे तौर पर अनुरोध करना

हमारा सुझाव है कि लागू करने के लिए, आप क्लाइंट लाइब्रेरी और सैंपल का इस्तेमाल करें. हालांकि, अगर एपीआई के साथ आपके इंटिग्रेशन के लिए खास ज़रूरतें हैं, जैसे कि इस्तेमाल न की जाने वाली भाषा का इस्तेमाल करना, तो नीचे बताए गए तरीके से सीधे अनुरोध किया जा सकता है.

कॉल करने का तरीका

REST, सॉफ़्टवेयर आर्किटेक्चर की एक स्टाइल है. यह डेटा का अनुरोध करने और उसमें बदलाव करने के लिए, आसान और एक जैसा तरीका उपलब्ध कराती है.

REST शब्द "रिप्रज़ेंटेशनल स्टेट ट्रांसफ़र" का छोटा रूप है. Google API के संदर्भ में, यह Google के सेव किए गए डेटा को दिखाने और उसमें बदलाव करने के लिए एचटीटीपी क्रियाओं का इस्तेमाल करता है.

RESTful सिस्टम में, संसाधनों को डेटा स्टोर में सेव किया जाता है. वहीं, क्लाइंट एक अनुरोध भेजता है कि सर्वर किसी खास काम (जैसे, संसाधन बनाना, वापस पाना, अपडेट करना या मिटाना) करता है. इसके बाद, सर्वर कार्रवाई करता है और जवाब देता है. आम तौर पर, यह अनुरोध, बताए गए संसाधन के तौर पर किया जाता है.

Google के RESTful एपीआई में, क्लाइंट एचटीटीपी कार्रवाई के बारे में बताता है, जैसे कि POST, GET, PUT या DELETE. यह ऐसे संसाधन के बारे में बताता है जो नीचे दिए गए फ़ॉर्म के दुनिया भर में मौजूद यूनीक यूआरआई की मदद से बनाया जाता है:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

सभी एपीआई संसाधनों में, एचटीटीपी से ऐक्सेस किए जा सकने वाले यूनीक यूआरआई होते हैं. इसलिए, REST डेटा कैश करने की सुविधा को चालू करती है. साथ ही, उसे वेब के डिस्ट्रिब्यूटेड इन्फ़्रास्ट्रक्चर के साथ काम करने के लिए ऑप्टिमाइज़ किया जाता है.

आपको एचटीटीपी 1.1 स्टैंडर्ड वाले दस्तावेज़ में तरीका की परिभाषाएं लग सकती हैं. इनमें GET, POST, PUT, और DELETE के लिए खास जानकारी शामिल होती है.

AdSense Management API में REST

इस्तेमाल की जा सकने वाली कार्रवाइयां, सीधे REST एचटीटीपी कार्रवाइयों से मैप करती हैं, जैसा कि AdSense Management API से जुड़ी कार्रवाइयों में बताया गया है.

AdSense Management API के यूआरआई का खास फ़ॉर्मैट इस तरह है:

https://adsense.googleapis.com/v2/resourceID?parameters

जहां resourceID, किसी विज्ञापन क्लाइंट, विज्ञापन यूनिट, यूआरएल चैनल, कस्टम चैनल या रिपोर्ट कलेक्शन का आइडेंटिफ़ायर होता है. इसके अलावा, parameters कोई भी पैरामीटर होता है जिसे क्वेरी पर लागू किया जा सकता है.

resourceID पाथ एक्सटेंशन के फ़ॉर्मैट की मदद से, आपको उस रिसॉर्स की पहचान करने में मदद मिलती है जिस पर फ़िलहाल काम किया जा रहा है, उदाहरण के लिए:

https://adsense.googleapis.com/v2/accounts/account_id/adclients
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/adunits
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/adunits/adUnitId
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/urlchannels
...

एपीआई में काम करने वाली हर कार्रवाई के लिए इस्तेमाल किए जाने वाले यूआरआई के पूरे सेट की खास जानकारी AdSense Management API का रेफ़रंस दस्तावेज़ में दी गई है.

यहां कुछ उदाहरण दिए गए हैं कि AdSense Management API में यह सुविधा कैसे काम करती है.

विज्ञापन क्लाइंट की सूची बनाएं:

GET https://adsense.googleapis.com/v2/accounts/account_id/adclients/

विज्ञापन क्लाइंट ca-pub-1234567890123456 में विज्ञापन यूनिट की सूची बनाएं:

GET https://adsense.googleapis.com/v2/accounts/account_id/adclients/ca-pub-1234567890123456/adunits

डेटा फ़ॉर्मैट

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

अनुमति के अनुरोध

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

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

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

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

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

AdSense Management API को किए जाने वाले सभी अनुरोधों की अनुमति, किसी ऐसे उपयोगकर्ता को दी जानी चाहिए जिसकी पुष्टि हो चुकी हो.

यह प्रोसेस, OAuth क्लाइंट आईडी की मदद से की जाती है.

OAuth क्लाइंट आईडी पाना

या क्रेडेंशियल पेज में जाकर क्रेडेंशियल बनाएं.

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

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

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

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

स्कोप	मतलब
https://www.googleapis.com/auth/adsense	AdSense डेटा के लिए पढ़ने/लिखने का ऐक्सेस.
https://www.googleapis.com/auth/adsense.readonly	AdSense डेटा के लिए रीड ओनली ऐक्सेस.

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

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

अनुरोध करना

आखिरी चरण में, एपीआई अनुरोध करना है. खास जानकारी के लिए, पहचान फ़ाइल के दस्तावेज़ देखें.