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

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

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

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

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

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

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

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

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

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

AdSense मैनेजमेंट एपीआई में REST

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

AdSense मैनेजमेंट एपीआई यूआरआई के लिए खास फ़ॉर्मैट ये हैं:

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 मैनेजमेंट एपीआई में यह कैसे काम करता है.

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

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 मैनेजमेंट एपीआई को जो भी अनुरोध भेजता है उसमें, अनुमति वाला टोकन शामिल होना चाहिए. इस टोकन से 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 की क्लाइंट लाइब्रेरी आपके लिए अनुमति देने की कुछ प्रक्रियाएं खुद कर सकती है. ये लाइब्रेरी कई प्रोग्रामिंग भाषाओं के लिए उपलब्ध होती हैं. ज़्यादा जानकारी के लिए लाइब्रेरी और नमूनों वाला पेज देखें.

अनुरोध करना

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