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

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

कॉल करने का स्टाइल

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

"Representational State Transfer" को कम शब्दों में REST कहते हैं. Google APIs के संदर्भ में, इसका मतलब 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 Management API में REST

इन कार्रवाइयों के लिए यह सुविधा उपलब्ध है. ये सीधे तौर पर REST एचटीटीपी वर्ब से मैप होती हैं.

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

अनुरोध करना

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