तृतीय-पक्ष API

Google Ads स्क्रिप्ट की एक बेहतरीन सुविधा यह है कि इसे तीसरे पक्ष के एपीआई के डेटा और सेवाओं के साथ इंटिग्रेट किया जा सकता है.

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

  • एचटीटीपी अनुरोध करना: बाहरी एपीआई को ऐक्सेस करने के लिए, UrlFetchApp का इस्तेमाल करने का तरीका.
  • पुष्टि करना: हम पुष्टि करने के कुछ सामान्य तरीकों के बारे में बताते हैं.
  • रिस्पॉन्स पार्स करना: रिटर्न किए गए JSON और एक्सएमएल डेटा को प्रोसेस करने का तरीका.

हम इन कॉन्सेप्ट को समझाने के लिए, कई लोकप्रिय एपीआई के सैंपल भी शामिल करते हैं.

UrlFetchApp की मदद से डेटा फ़ेच करना

UrlFetchApp, तीसरे पक्ष के एपीआई के साथ इंटरैक्ट करने के लिए ज़रूरी मुख्य फ़ंक्शन उपलब्ध कराता है.

इस उदाहरण में, OpenWeatherMap से मौसम का डेटा फ़ेच करने का तरीका बताया गया है. हमने अनुमति देने की योजना और एपीआई के आसान होने की वजह से, OpenWeatherMap को चुना है.

अनुरोध करें

OpenWeatherMap के दस्तावेज़ में, मौसम की मौजूदा स्थिति के अनुरोध के लिए, फ़ॉर्मैट के बारे में इस तरह बताया गया है:

http://api.openweathermap.org/data/2.5/weather?q=[location]&apikey=[apikey]

यूआरएल, अनुमति का पहला उदाहरण देता है: पैरामीटर apikey ज़रूरी है और हर उपयोगकर्ता के लिए वैल्यू अलग-अलग होती है. यह कुंजी, साइन अप करने पर मिलती है.

साइन अप करने के बाद, पासकोड का इस्तेमाल करके अनुरोध इस तरह किया जा सकता है:

const location = 'London,uk';
const apikey = 'da.......................81'; // Replace with your API key
const currentWeatherUrl = `http://api.openweathermap.org/data/2.5/weather?q=${location}&apiKey=${apiKey}`;
const response = UrlFetchApp.fetch(currentWeatherUrl);
console.log(response.getContentText());

इस कोड को लागू करने पर, Google Ads स्क्रिप्ट की लॉगिंग विंडो में JSON टेक्स्ट की एक लंबी स्ट्रिंग बन जाती है.

अगले चरण में, इसे ऐसे फ़ॉर्मैट में बदलना है जिसका इस्तेमाल आपकी स्क्रिप्ट में किया जा सके.

JSON डेटा

कई एपीआई, JSON फ़ॉर्मैट में जवाब देते हैं. यह JavaScript ऑब्जेक्ट के सीरियलाइज़ेशन को आसानी से दिखाता है. इससे ऑब्जेक्ट, कलेक्शन, और बुनियादी टाइप को स्ट्रिंग के तौर पर दिखाया और ट्रांसफ़र किया जा सकता है.

किसी JSON स्ट्रिंग को JavaScript ऑब्जेक्ट में बदलने के लिए, पहले से मौजूद JSON.parse तरीके का इस्तेमाल करें. जैसे, OpenWeatherMap से मिली स्ट्रिंग. ऊपर दिए गए उदाहरण को जारी रखते हुए:

const json = response.getContentText();
const weatherData = JSON.parse(json);
console.log(weatherData.name);
//  "London"

JSON.parse तरीका, स्ट्रिंग को ऐसे ऑब्जेक्ट में बदलता है जिसमें एक प्रॉपर्टी name होती है.

अलग-अलग फ़ॉर्मैट में एपीआई रिस्पॉन्स के साथ काम करने के बारे में ज़्यादा जानकारी के लिए, रिस्पॉन्स पार्स करना सेक्शन देखें.

गड़बड़ी ठीक करना

अपनी स्क्रिप्ट में तीसरे पक्ष के एपीआई के साथ काम करते समय, गड़बड़ी को मैनेज करना एक अहम बात है. ऐसा इसलिए, क्योंकि तीसरे पक्ष के एपीआई अक्सर बदलते रहते हैं और रिस्पॉन्स की अनचाही वैल्यू जनरेट करते हैं. उदाहरण के लिए:

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

एचटीटीपी स्टेटस कोड

अनचाहे रिस्पॉन्स मिलने की संभावना होने की वजह से, आपको एचटीटीपी स्टेटस कोड की जांच करनी चाहिए. डिफ़ॉल्ट रूप से, एचटीटीपी गड़बड़ी कोड मिलने पर, UrlFetchApp एक अपवाद दिखाएगा. इस व्यवहार को बदलने के लिए, वैकल्पिक पैरामीटर को पास करना ज़रूरी है, जैसा कि नीचे दिए गए उदाहरण में बताया गया है:

const options = {
  muteHttpExceptions: true
}
const response = UrlFetchApp.fetch(url, options);
// Any status code greater or equal to 400 is either a client or server error.
if (response.getResponseCode() >= 400) {
  // Error encountered, send an email alert to the developer
  sendFailureEmail();
}

रिस्पॉन्स का स्ट्रक्चर

तीसरे पक्ष के एपीआई में बदलाव होने पर, डेवलपर को अक्सर उन बदलावों के बारे में तुरंत पता नहीं चलता जिनका असर उनकी स्क्रिप्ट पर पड़ सकता है. उदाहरण के लिए, अगर OpenWeatherMap के उदाहरण में दिखाई गई name प्रॉपर्टी को locationName में बदल दिया जाता है, तो इस प्रॉपर्टी का इस्तेमाल करने वाली स्क्रिप्ट काम नहीं करेंगी.

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

const weatherData = JSON.parse(json);
if (weatherData && weatherData.name) {
  console.log('Location is : ' + name);
} else {
  console.log('Data not in expected format');
}

UrlFetchApp की मदद से डेटा पोस्ट करना

OpenWeatherMap के साथ शुरुआती उदाहरण, जिसमें सिर्फ़ फ़ेच किया गया डेटा है. आम तौर पर, ऐसे एपीआई कॉल जिनसे रिमोट सर्वर पर स्टेटस में बदलाव नहीं होता, वे HTTP GET वाले तरीके का इस्तेमाल करते हैं.

GET का तरीका, UrlFetchApp के लिए डिफ़ॉल्ट तौर पर सेट होता है. हालांकि, एसएमएस मैसेज भेजने वाली सेवा के कॉल जैसे कुछ एपीआई कॉल के लिए, POST या PUT जैसे अन्य तरीकों की ज़रूरत होगी.

POST कॉल के साथ UrlFetchApp का इस्तेमाल करने के बारे में बताने के लिए, यहां दिए गए उदाहरण में Slack के साथ इंटिग्रेशन के बारे में बताया गया है. यह एक ऐसा मैसेजिंग ऐप्लिकेशन है जिसमें कई लोग साथ मिलकर काम कर सकते हैं. इसकी मदद से, Slack के उपयोगकर्ताओं और ग्रुप को मैसेज भेजा जा सकता है.

Slack सेट अप करना

इस गाइड में यह माना गया है कि आपने पहले ही Slack खाते के लिए साइन अप कर लिया है.

पिछले उदाहरण में OpenWeatherMap की तरह, मैसेज भेजने की सुविधा चालू करने के लिए टोकन पाना ज़रूरी है. Slack आपको एक यूनीक यूआरएल देता है, जिसकी मदद से अपनी टीम को मैसेज भेजे जा सकते हैं. इसे इनकमिंग वेबहुक कहा जाता है.

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

POST अनुरोध करना

इनकमिंग वेबहुक सेट अप करने के बाद, POST अनुरोध करने के लिए, UrlFetchApp.fetch को पास किए गए options पैरामीटर में कुछ अतिरिक्त प्रॉपर्टी का इस्तेमाल करना ज़रूरी है:

  • method: जैसा कि बताया गया है, यह डिफ़ॉल्ट रूप से GET पर सेट होता है. हालांकि, यहां हम इसे बदलकर POST पर सेट करते हैं.

  • payload: यह वह डेटा है जिसे POST के अनुरोध के हिस्से के तौर पर सर्वर पर भेजा जाना है. इस उदाहरण में, Slack को JSON फ़ॉर्मैट में सिलसिलेवार तरीके से व्यवस्थित किया गया ऑब्जेक्ट चाहिए, जैसा कि Slack के दस्तावेज़ में बताया गया है. इसके लिए, JSON.stringify तरीके का इस्तेमाल किया जाता है और Content-Type को application/json पर सेट किया जाता है.

      // Change the URL for the one issued to you from 'Setting up Slack'.
  const SLACK_URL = 'https://hooks.slack.com/services/AAAA/BBBB/CCCCCCCCCC';
  const slackMessage = {
    text: 'Hello, slack!'
  };

  const options = {
    method: 'POST',
    contentType: 'application/json',
    payload: JSON.stringify(slackMessage)
  };
  UrlFetchApp.fetch(SLACK_URL, options);

Slack के लिए एक्सटेंड किए गए वर्शन का उदाहरण

ऊपर दिए गए उदाहरण में, Slack में आने वाले मैसेज की सुविधा चालू करने के लिए, कम से कम ज़रूरी शर्तें बताई गई हैं. बड़े सैंपल में, किसी ग्रुप को कैंपेन की परफ़ॉर्मेंस रिपोर्ट बनाने और भेजने के साथ-साथ, फ़ॉर्मैटिंग और डिसप्ले के कुछ विकल्पों के बारे में बताया गया है.

आने वाला मैसेज

Slack मैसेज के बारे में ज़्यादा जानकारी के लिए, Slack के दस्तावेज़ में मैसेज फ़ॉर्मैट करना देखें.

फ़ॉर्म डेटा

ऊपर दिए गए उदाहरण में, POST अनुरोध के लिए payload प्रॉपर्टी के तौर पर JSON स्ट्रिंग का इस्तेमाल किया गया है.

payload के फ़ॉर्मैट के आधार पर, UrlFetchApp POST अनुरोध को बनाने के लिए अलग-अलग तरीके अपनाता है:

  • जब payload कोई स्ट्रिंग है, तो स्ट्रिंग आर्ग्युमेंट को अनुरोध के मुख्य हिस्से के तौर पर भेजा जाता है.

  • जब payload कोई ऑब्जेक्ट हो, जैसे कि वैल्यू का मैप:

    {to: 'mail@example.com', subject:'Test', body:'Hello, World!'}

    की/वैल्यू पेयर को फ़ॉर्म-डेटा में बदल दिया जाता है:

    subject=Test&to=mail@example.com&body=Hello,+World!

    साथ ही, अनुरोध के लिए Content-Type हेडर को application/x-www-form-urlencoded पर सेट किया गया है.

कुछ एपीआई के लिए, पोस्ट अनुरोध सबमिट करते समय फ़ॉर्म डेटा का इस्तेमाल करना ज़रूरी होता है. इसलिए, JavaScript ऑब्जेक्ट से फ़ॉर्म डेटा में अपने-आप होने वाले कन्वर्ज़न को ध्यान में रखना ज़रूरी है.

एचटीटीपी की बुनियादी पुष्टि

एचटीटीपी से पुष्टि करने की बुनियादी सुविधा, पुष्टि करने के सबसे आसान तरीकों में से एक है. इसका इस्तेमाल कई एपीआई करते हैं.

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

एचटीटीपी की बुनियादी पुष्टि

अनुरोध बनाना

पुष्टि किए गए अनुरोध को जनरेट करने के लिए, यह तरीका अपनाएं:

  1. उपयोगकर्ता नाम और पासवर्ड को कोलन के साथ जोड़कर पासफ़्रेज़ बनाएं. उदाहरण के लिए, username:password.
  2. पासफ़्रेज़ को Base64 कोड में बदलें. उदाहरण के लिए, username:password को dXNlcm5hbWU6cGFzc3dvcmQ= में बदला जाता है.
  3. अनुरोध में Authorization हेडर को Authorization: Basic <encoded passphrase> फ़ॉर्म में अटैच करें

नीचे दिए गए स्निपेट में, Google Ads स्क्रिप्ट में ऐसा करने का तरीका बताया गया है:

const USERNAME = 'your_username';
const PASSWORD = 'your_password';
const API_URL = 'http://<place_api_url_here>';

const authHeader = 'Basic ' + Utilities.base64Encode(USERNAME + ':' + PASSWORD);
const options = {
  headers: {Authorization: authHeader}
}
// Include 'options' object in every request
const response = UrlFetchApp.fetch(API_URL, options);

बुनियादी पुष्टि के सैंपल

कोड के सैंपल सेक्शन में, एचटीटीपी बुनियादी पुष्टि करने के तरीके का इस्तेमाल करने के दो सैंपल दिए गए हैं:

Plivo

Plivo एक ऐसी सेवा है जो अपने एपीआई की मदद से, एसएमएस मैसेज भेजने और पाने की सुविधा देती है. इस सैंपल में, मैसेज भेजने का तरीका बताया गया है.

  1. Plivo पर रजिस्टर करें.
  2. सैंपल स्क्रिप्ट को Google Ads में नई स्क्रिप्ट में चिपकाएं.
  3. PLIVO_ACCOUNT_AUTHID और PLIVO_ACCOUNT_AUTHTOKEN वैल्यू को मैनेजमेंट डैशबोर्ड की वैल्यू से बदलें.
  4. गड़बड़ियों की सूचना पाने के लिए, स्क्रिप्ट में बताए गए तरीके से अपना ईमेल पता डालें.
  5. Plivo का इस्तेमाल करने के लिए, आपको नंबर खरीदने होंगे या मुफ़्त में आज़माने के लिए उपलब्ध खाते में नंबर जोड़ने होंगे. सैंडबॉक्स नंबर जोड़ें, जिनका इस्तेमाल, ट्रायल खाते के साथ किया जा सकता है.
  6. वह नंबर जो ईमेल भेजने वाले के तौर पर दिखेगा और वह नंबर जो ईमेल पाने वाले के तौर पर दिखेगा, दोनों जोड़ें.
  7. स्क्रिप्ट में PLIVO_SRC_PHONE_NUMBER को, अभी-अभी रजिस्टर किए गए सैंडबॉक्स नंबर में से किसी एक पर अपडेट करें. इसमें देश का अंतरराष्ट्रीय कोड शामिल होना चाहिए. उदाहरण के लिए, यूनाइटेड किंगडम के नंबर के लिए 447777123456.

Twilio

Twilio एक और सेवा है, जो अपने एपीआई के ज़रिए एसएमएस मैसेज भेजने और पाने की सुविधा देती है. इस सैंपल में, मैसेज भेजने का तरीका बताया गया है.

  1. Twillio पर रजिस्टर करें.
  2. Google Ads में नई स्क्रिप्ट में, सैंपल स्क्रिप्ट चिपकाएं.
  3. TWILIO_ACCOUNT_SID और TWILIO_ACCOUNT_AUTHTOKEN वैल्यू को खाता कंसोल पेज पर दिखाई गई वैल्यू से बदलें.
  4. TWILIO_SRC_PHONE_NUMBER को डैशबोर्ड में मौजूद नंबर से बदलें. यह वह नंबर है जिसे मैसेज भेजने के लिए Twilio ने अनुमति दी है.

OAuth 1.0

कई लोकप्रिय सेवाएं, पुष्टि करने के लिए OAuth का इस्तेमाल करती हैं. OAuth कई तरह के और वर्शन में उपलब्ध है.

एचटीटीपी बुनियादी पुष्टि की सुविधा में, उपयोगकर्ता के पास सिर्फ़ एक उपयोगकर्ता नाम और पासवर्ड होता है. वहीं, OAuth की मदद से तीसरे पक्ष के ऐप्लिकेशन को, उपयोगकर्ता के खाते और डेटा का ऐक्सेस दिया जा सकता है. इसके लिए, तीसरे पक्ष के ऐप्लिकेशन के लिए खास तौर पर क्रेडेंशियल का इस्तेमाल किया जाता है. इसके अलावा, ऐक्सेस का दायरा भी उस ऐप्लिकेशन के हिसाब से तय होगा.

OAuth 1.0 के बारे में जानकारी पाने के लिए, OAuth कोर गाइड देखें. खास तौर पर, 6. OAuth से पुष्टि करना. OAuth 1.0 के तीन चरणों वाली पूरी प्रोसेस इस तरह होती है:

  1. ऐप्लिकेशन ("उपभोक्ता") को अनुरोध टोकन मिलता है.
  2. उपयोगकर्ता, अनुरोध टोकन को अनुमति देता है.
  3. ऐप्लिकेशन, अनुरोध टोकन को ऐक्सेस टोकन से बदल देता है.
  4. संसाधन के लिए किए जाने वाले सभी अनुरोधों के लिए, हस्ताक्षर किए गए अनुरोध में ऐक्सेस टोकन का इस्तेमाल किया जाता है.

तीसरे पक्ष की सेवाओं के लिए, उपयोगकर्ता के इंटरैक्शन के बिना OAuth 1.0 का इस्तेमाल करना संभव नहीं है. उदाहरण के लिए, Google Ads स्क्रिप्ट के लिए पहला, दूसरा, और तीसरा चरण पूरा नहीं किया जा सकता. इसलिए, कुछ सेवाएं अपने कॉन्फ़िगरेशन कंसोल से ऐक्सेस टोकन जारी करती हैं. इससे ऐप्लिकेशन सीधे चौथे चरण पर जा सकता है. इसे एक-लेग वाला OAuth 1.0 कहा जाता है.

OAuth1

Google Ads स्क्रिप्ट में OAuth 1.0

Google Ads स्क्रिप्ट के लिए, आम तौर पर हर स्क्रिप्ट को ऐप्लिकेशन के तौर पर समझा जाता है. आम तौर पर, सेवा के लिए कंसोल/एडमिन सेटिंग पेज पर जाकर, ये काम करने होंगे:

  • स्क्रिप्ट को दिखाने के लिए, ऐप्लिकेशन कॉन्फ़िगरेशन सेट अप करें.
  • बताएं कि स्क्रिप्ट को कौनसी अनुमतियां दी जा रही हैं.
  • वन-लेग OAuth के साथ इस्तेमाल करने के लिए, उपयोगकर्ता कुंजी, उपयोगकर्ता सीक्रेट, ऐक्सेस टोकन, और ऐक्सेस सीक्रेट पाएं.

OAuth 2.0

OAuth 2.0 का इस्तेमाल, उपयोगकर्ता के डेटा का ऐक्सेस देने के लिए, लोकप्रिय एपीआई में किया जाता है. तीसरे पक्ष की किसी सेवा के लिए बनाए गए खाते का मालिक, कुछ ऐप्लिकेशन को उपयोगकर्ता का डेटा ऐक्सेस करने की अनुमति देता है. इसके ये फ़ायदे हैं:

  • उन्हें ऐप्लिकेशन के साथ अपने खाते के क्रेडेंशियल शेयर करने की ज़रूरत नहीं होती.
  • यह कंट्रोल किया जा सकता है कि किन ऐप्लिकेशन के पास डेटा का ऐक्सेस है और किस हद तक है. (उदाहरण के लिए, ऐक्सेस सिर्फ़ पढ़ने के लिए दिया जा सकता है या सिर्फ़ डेटा के सबसेट के लिए दिया जा सकता है.)

Google Ads स्क्रिप्ट में, OAuth 2.0 की सुविधा वाली सेवाओं का इस्तेमाल करने के लिए, ये कई चरण पूरे करने होंगे:

आपकी स्क्रिप्ट के बाहर

तीसरे पक्ष के एपीआई के ज़रिए, अपने उपयोगकर्ता का डेटा ऐक्सेस करने के लिए, Google Ads स्क्रिप्ट को अनुमति दें. ज़्यादातर मामलों में, तीसरे पक्ष की सेवा के कंसोल में ऐप्लिकेशन सेट अप करना होगा. यह ऐप्लिकेशन, आपकी Google Ads स्क्रिप्ट को दिखाता है.

आपके पास यह तय करने का विकल्प होता है कि Google Ads स्क्रिप्ट ऐप्लिकेशन को ऐक्सेस करने के कौनसे अधिकार देने हैं. आम तौर पर, इसे एक क्लाइंट आईडी असाइन किया जाता है. इससे आपको OAuth 2 की मदद से यह कंट्रोल करने की सुविधा मिलती है कि तीसरे पक्ष की सेवा में कौनसे ऐप्लिकेशन आपके डेटा को ऐक्सेस कर सकते हैं. साथ ही, यह भी कंट्रोल किया जा सकता है कि वे उस डेटा के किन हिस्सों को देख सकते हैं या उनमें बदलाव कर सकते हैं.

आपकी स्क्रिप्ट में

रिमोट सर्वर से अनुमति पाएं. सर्वर ने जिस अनुमति टाइप की अनुमति दी है उसके आधार पर, फ़्लो के तौर पर जाने वाले अलग-अलग चरणों को पूरा करना होगा. हालांकि, इन सभी चरणों के बाद, एक ऐक्सेस टोकन जारी किया जाएगा. इसका इस्तेमाल, उस सेशन के लिए किए जाने वाले सभी अनुरोधों के लिए किया जाएगा.

एपीआई अनुरोध करना. हर अनुरोध के साथ ऐक्सेस टोकन पास करें.

अनुमति देने के फ़्लो

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

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

लागू करना

OAuth के सभी अलग-अलग फ़्लो का मकसद, ऐक्सेस टोकन पाना होता है. इसके बाद, इस टोकन का इस्तेमाल बाकी सेशन के लिए, अनुरोधों की पुष्टि करने के लिए किया जा सकता है.

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

इसका इस्तेमाल करने का सामान्य तरीका यह है:

// Authenticate using chosen flow type
const urlFetchObj = OAuth2.<flow method>(args);
// Make request(s) using obtained object.
const response1 = urlFetchObj.fetch(url1);
const response2 = urlFetchObj.fetch(url2, options);

क्लाइंट क्रेडेंशियल

क्लाइंट क्रेडेंशियल का अनुदान, OAuth2 फ़्लो का एक आसान तरीका है. इसमें ऐप्लिकेशन, समयसीमा वाले ऐक्सेस टोकन जारी करने के बदले, ऐप्लिकेशन के लिए यूनीक आईडी और सीक्रेट का आदान-प्रदान करता है.

क्लाइंट क्रेडेंशियल

// Access token is obtained and cached.
const authUrlFetch = OAuth2.withClientCredentials(
    tokenUrl, clientId, clientSecret, optionalScope));
// Use access token in each request
const response = authUrlFetch.fetch(url);
// ... use response

रीफ़्रेश टोकन

रीफ़्रेश टोकन का अनुदान, क्लाइंट क्रेडेंशियल के अनुदान जैसा ही है. इसकी वजह यह है कि सर्वर से किए गए एक सामान्य अनुरोध से, ऐक्सेस टोकन मिलेगा. इसका इस्तेमाल सेशन में किया जा सकता है.

रीफ़्रेश टोकन

रीफ़्रेश टोकन पाना

रीफ़्रेश टोकन देने की प्रोसेस और क्लाइंट क्रेडेंशियल देने की प्रोसेस में अंतर यह है कि क्लाइंट क्रेडेंशियल देने के लिए ज़रूरी जानकारी, ऐप्लिकेशन कॉन्फ़िगरेशन से मिलती है. उदाहरण के लिए, सेवा के कंट्रोल पैनल में. वहीं, रीफ़्रेश टोकन, अनुमति कोड देने जैसी ज़्यादा जटिल प्रोसेस के हिस्से के तौर पर दिया जाता है. इसके लिए, उपयोगकर्ता के इंटरैक्शन की ज़रूरत होगी:

प्राधिकरण कोड

रीफ़्रेश टोकन पाने के लिए, OAuth Playground का इस्तेमाल करना

OAuth2 प्लेलैंड एक ऐसा यूज़र इंटरफ़ेस (यूआई) उपलब्ध कराता है जिसकी मदद से उपयोगकर्ता, रीफ़्रेश टोकन पाने के लिए ऑथराइज़ेशन कोड पाने की प्रोसेस को पूरा कर सकता है.

सबसे ऊपर दाईं ओर मौजूद सेटिंग बटन की मदद से, OAuth फ़्लो में इस्तेमाल किए जाने वाले सभी पैरामीटर तय किए जा सकते हैं. इनमें ये शामिल हैं:

  • ऑथराइज़ेशन एंडपॉइंट: इसका इस्तेमाल, अनुमति देने के फ़्लो की शुरुआत के तौर पर किया जाता है.
  • टोकन एंडपॉइंट: ऐक्सेस टोकन पाने के लिए, रिफ़्रेश टोकन के साथ इस्तेमाल किया जाता है.
  • क्लाइंट आईडी और सीक्रेट: ऐप्लिकेशन के लिए क्रेडेंशियल.

OAuth Playground

रीफ़्रेश टोकन पाने के लिए स्क्रिप्ट का इस्तेमाल करना

रिफ़्रेश टोकन जनरेट करने के सैंपल में, स्क्रिप्ट के आधार पर फ़्लो पूरा करने का विकल्प उपलब्ध है.

रीफ़्रेश टोकन का इस्तेमाल

शुरुआती अनुमति मिलने के बाद, सेवाएं रीफ़्रेश टोकन जारी कर सकती हैं. इसका इस्तेमाल, क्लाइंट क्रेडेंशियल फ़्लो की तरह ही किया जा सकता है. नीचे दो उदाहरण दिए गए हैं:

const authUrlFetch = OAuth2.withRefreshToken(tokenUrl, clientId, clientSecret,
    refreshToken, optionalScope);
const response = authUrlFetch.fetch(url);
// ... use response

Search Ads 360 का उदाहरण

Search Ads 360, ऐसे एपीआई का उदाहरण है जिसका इस्तेमाल रीफ़्रेश टोकन के साथ किया जा सकता है. इस सैंपल में, स्क्रिप्ट रिपोर्ट जनरेट करती है और उसे दिखाती है. की जाने वाली अन्य कार्रवाइयों के बारे में पूरी जानकारी के लिए, Search Ads 360 API रेफ़रंस देखें.

स्क्रिप्ट बनाना
  1. एपीआई कंसोल में नया प्रोजेक्ट बनाएं और DoubleClick गाइड में बताए गए तरीके का पालन करके क्लाइंट आईडी, क्लाइंट पासवर्ड, और रीफ़्रेश टोकन पाएं. साथ ही, पक्का करें कि आपने DoubleClick Search API चालू किया हो.
  2. सैंपल स्क्रिप्ट को Google Ads में नई स्क्रिप्ट में चिपकाएं.
  3. कोड लिस्टिंग के नीचे, OAuth2 की सैंपल लाइब्रेरी चिपकाएं.
  4. क्लाइंट आईडी, क्लाइंट सीक्रेट, और रीफ़्रेश टोकन की सही वैल्यू शामिल करने के लिए, स्क्रिप्ट में बदलाव करें.

Apps Script Execution API का उदाहरण

इस उदाहरण में, Apps Script Execution API का इस्तेमाल करके, Apps Script में फ़ंक्शन को लागू करने का तरीका बताया गया है. इससे, Google Ads स्क्रिप्ट से Apps Script को कॉल किया जा सकता है.

Apps Script स्क्रिप्ट बनाना

नई स्क्रिप्ट बनाएं. इस सैंपल में, Drive में मौजूद 10 फ़ाइलों की सूची दी गई है:

function listFiles() {
  const limit = 10;
  const files = [];
  const fileIterator = DriveApp.getFiles();
  while (fileIterator.hasNext() && limit) {
    files.push(fileIterator.next().getName());
    limit--;
  }
  return files;
}
Apps Script को लागू करने के लिए कॉन्फ़िगर करना
  1. स्क्रिप्ट सेव करें.
  2. संसाधन > Cloud Platform प्रोजेक्ट पर क्लिक करें.
  3. API Console पर जाने के लिए, प्रोजेक्ट के नाम पर क्लिक करें.
  4. एपीआई और सेवाएं पर जाएं.
  5. ज़रूरी एपीआई चालू करें. इस मामले में, Drive API और Apps Script Execution API.
  6. मेन्यू में क्रेडेंशियल आइटम से OAuth क्रेडेंशियल बनाएं.
  7. अपनी स्क्रिप्ट पर वापस जाकर, पब्लिश करें > एपीआई निष्पादन-योग्य के तौर पर डिप्लॉय करें से, स्क्रिप्ट को निष्पादन के लिए पब्लिश करें.
Google Ads स्क्रिप्ट बनाना
  1. सैंपल स्क्रिप्ट को Google Ads में नई स्क्रिप्ट में चिपकाएं.
  2. इसके अलावा, कोड लिस्टिंग के नीचे OAuth2 लाइब्रेरी का सैंपल चिपकाएं.
  3. क्लाइंट आईडी, क्लाइंट सीक्रेट, और रीफ़्रेश टोकन की सही वैल्यू शामिल करने के लिए, स्क्रिप्ट में बदलाव करें.

सेवा खाते

ऊपर बताए गए अनुदान के टाइप के अलावा, सेवा खातों का भी विकल्प है.

सेवा खाते, ऊपर बताए गए खातों से अलग होते हैं. इनका इस्तेमाल, उपयोगकर्ता के डेटा को ऐक्सेस करने के लिए नहीं किया जाता: पुष्टि करने के बाद, सेवा खाता ऐप्लिकेशन की ओर से अनुरोध करता है, न कि प्रोजेक्ट के मालिक के तौर पर. उदाहरण के लिए, अगर सेवा खाता फ़ाइल बनाने के लिए Drive API का इस्तेमाल करता है, तो यह फ़ाइल सेवा खाते की होगी और डिफ़ॉल्ट रूप से, प्रोजेक्ट के मालिक के पास इसका ऐक्सेस नहीं होगा.

Google के Natural Language API का उदाहरण

नैचुरल लैंग्वेज एपीआई, टेक्स्ट के लिए भावनाओं का विश्लेषण और इकाई का विश्लेषण करता है.

इस उदाहरण में, विज्ञापन टेक्स्ट के लिए भावना का हिसाब लगाने का तरीका बताया गया है. इसमें हेडलाइन या ब्यौरा भी शामिल है. इससे यह पता चलता है कि मैसेज कितना सकारात्मक है और उसका असर कितना है: इनमें से कौनसा मैसेज बेहतर है, हम केक बेचते हैं या हम लंदन में सबसे अच्छे केक बेचते हैं. आज ही खरीदें!?

स्क्रिप्ट सेट अप करना
  1. API Console में नया प्रोजेक्ट बनाएं
  2. Natural Language API चालू करना
  3. प्रोजेक्ट के लिए बिलिंग चालू करें.
  4. सेवा खाता बनाएं. क्रेडेंशियल की JSON फ़ाइल डाउनलोड करें.
  5. Google Ads में नई स्क्रिप्ट में, सैंपल स्क्रिप्ट चिपकाएं.
  6. इसके अलावा, कोड लिस्टिंग के नीचे OAuth2 लाइब्रेरी का सैंपल चिपकाएं.
  7. ज़रूरी वैल्यू बदलें:
    • serviceAccount: सेवा खाते का ईमेल पता, उदाहरण के लिए xxxxx@yyyy.iam.gserviceaccount.com.
    • key: सेवा खाता बनाते समय डाउनलोड की गई JSON फ़ाइल की कुंजी. -----BEGIN PRIVATE KEY... से शुरू होकर ...END PRIVATE KEY-----\n पर खत्म होता है.

एपीआई से मिले रिस्पॉन्स

एपीआई, डेटा को कई फ़ॉर्मैट में दिखा सकते हैं. इनमें से सबसे ज़्यादा इस्तेमाल होने वाले फ़ॉर्मैट, एक्सएमएल और JSON हैं.

JSON

आम तौर पर, रिस्पॉन्स फ़ॉर्मैट के तौर पर काम करने के लिए, JSON का इस्तेमाल करना एक्सएमएल के मुकाबले आसान होता है. हालांकि, अब भी कुछ समस्याएं आ सकती हैं.

प्रतिक्रिया पुष्टि

एपीआई को कॉल करने पर, JSON स्ट्रिंग को JavaScript ऑब्जेक्ट में बदलने के लिए, JSON.parse का इस्तेमाल किया जाता है. इस स्थिति में, पार्स करने की प्रोसेस पूरी न हो पाने की स्थिति को मैनेज करना सही रहता है:

const json = response.getContentText();
try {
  const data = JSON.parse(json);
  return data;
} catch(e) {
  // Parsing of JSON failed - handle error.
}

अगर एपीआई आपके कंट्रोल में नहीं है, तो ध्यान रखें कि रिस्पॉन्स का स्ट्रक्चर बदल सकता है और हो सकता है कि प्रॉपर्टी अब मौजूद न हों:

// Less good approach
// Assumes JSON was in form {"queryResponse": ...} when parsed.
const answer = data.queryResponse;

// Better approach
if (data && data.queryResponse) {
  const answer = data.queryResponse;
} else {
  // Format of API response has changed - alert developer or handle accordingly
}

XML

पुष्टि

एपीआई बनाने के लिए, एक्सएमएल अब भी एक लोकप्रिय फ़ॉर्मैट है. एपीआई कॉल के रिस्पॉन्स को XmlService parse तरीके का इस्तेमाल करके पार्स किया जा सकता है:

const responseText = response.getContentText();
try {
  const document = XmlService.parse(responseText);
} catch(e) {
  // Error in XML representation - handle accordingly.
}

XmlService.parse, एक्सएमएल में गड़बड़ियों का पता लगाता है और उनसे जुड़े अपवाद दिखाता है. हालांकि, यह एक्सएमएल की पुष्टि किसी स्कीमा के आधार पर नहीं करता.

रूट एलिमेंट

एक्सएमएल दस्तावेज़ को पार्स करने के बाद, getRootElement() तरीके का इस्तेमाल करके रूट एलिमेंट पाया जाता है:

const document = XmlService.parse(responseText);
const rootElement = document.getRootElement();

नाम स्थान

नीचे दिए गए उदाहरण में, चुने गए मैचों के फ़ुटबॉल नतीजे पाने के लिए, Sportradar API का इस्तेमाल किया गया है. एक्सएमएल रिस्पॉन्स का फ़ॉर्मैट यह है:

<schedule xmlns="http://feed.elasticstats.com/schema/soccer/sr/v2/matches-schedule.xsd">
  <matches>
     ...
  </matches>
</schedule>

ध्यान दें कि रूट एलिमेंट में नेमस्पेस को कैसे बताया गया है. इसलिए, यह ज़रूरी है कि:

  • दस्तावेज़ से नेमस्पेस एट्रिब्यूट निकालें.
  • चाइल्ड एलिमेंट को ट्रैवर्स और ऐक्सेस करते समय, इस नेमस्पेस का इस्तेमाल करें.

यहां दिए गए सैंपल में, ऊपर दिए गए दस्तावेज़ के स्निपेट में <matches> एलिमेंट को ऐक्सेस करने का तरीका बताया गया है:

const document = XmlService.parse(xmlText);
const scheduleElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = scheduleElement.getNamespace();
const matchesElement = scheduleElement.getChild('matches', namespace);

वैल्यू पाना

फ़ुटबॉल के शेड्यूल का सैंपल:

<match status="..." category="..." ... >
  ...
</match>

एट्रिब्यूट वापस पाए जा सकते हैं. उदाहरण के लिए:

const status = matchElement.getAttribute('status').getValue();

किसी एलिमेंट में मौजूद टेक्स्ट को getText() का इस्तेमाल करके पढ़ा जा सकता है. हालांकि, अगर किसी एलिमेंट के कई टेक्स्ट चाइल्ड हैं, तो उन्हें आपस में जोड़ दिया जाएगा. अगर एक से ज़्यादा टेक्स्ट चाइल्ड होने की संभावना है, तो getChildren() का इस्तेमाल करें और हर चाइल्ड पर बार-बार जाएं.

Sportradar का उदाहरण

Sportradar के इस उदाहरण में, फ़ुटबॉल मैचों की जानकारी पाने का तरीका बताया गया है. खास तौर पर, इंग्लिश प्रीमियर लीग के मैचों की जानकारी पाने का तरीका. Soccer API, Sportradar के ज़रिए उपलब्ध कराए जाने वाले कई स्पोर्ट्स फ़ीड में से एक है.

Sportradar खाता सेट अप करना
  1. Sportradar की डेवलपर साइट पर जाएं
  2. मुफ़्त में आज़माने के लिए उपलब्ध खाते के लिए रजिस्टर करें.
  3. रजिस्टर करने के बाद, अपने खाते में साइन इन करें.
  4. लॉग इन करने के बाद, MyAccount पर जाएं.

Sportradar, अलग-अलग खेलों को अलग-अलग एपीआई में बांटता है. उदाहरण के लिए, हो सकता है कि आपने फ़ुटबॉल एपीआई का ऐक्सेस खरीदा हो, लेकिन टेनिस एपीआई का नहीं. आपके बनाए गए हर ऐप्लिकेशन में अलग-अलग स्पोर्ट्स और अलग-अलग बटन हो सकते हैं.

  1. 'ऐप्लिकेशन' में जाकर, नया ऐप्लिकेशन बनाएं पर क्लिक करें. ऐप्लिकेशन को नाम और ब्यौरा दें. वेबसाइट फ़ील्ड को अनदेखा करें.
  2. सिर्फ़ Soccer Trial Europe v2 के लिए नया पासकोड जारी करें को चुनें.
  3. ऐप्लिकेशन रजिस्टर करें पर क्लिक करें.

ऐसा करने के बाद, आपको एक पेज दिखेगा. इस पेज पर आपकी नई एपीआई पासकोड होगी.

  1. Google Ads में नई स्क्रिप्ट में, सैंपल स्क्रिप्ट चिपकाएं.
  2. लिस्टिंग में एपीआई पासकोड को ऊपर मिली पासकोड से बदलें और ईमेल पते के फ़ील्ड में बदलाव करें.

समस्या का हल

तीसरे पक्ष के एपीआई का इस्तेमाल करने पर, कई वजहों से गड़बड़ियां हो सकती हैं. उदाहरण के लिए:

  • ऐसे क्लाइंट जो सर्वर को ऐसे फ़ॉर्मैट में अनुरोध भेजते हैं जो एपीआई के हिसाब से नहीं है.
  • क्लाइंट को जवाब का ऐसा फ़ॉर्मैट चाहिए जो उन्हें नहीं मिला.
  • अमान्य टोकन या कुंजियों का इस्तेमाल करने वाले क्लाइंट या प्लेसहोल्डर के तौर पर छोड़ी गई वैल्यू.
  • ऐसे क्लाइंट जिनके लिए इस्तेमाल की सीमा पूरी हो गई है.
  • अमान्य पैरामीटर देने वाले क्लाइंट.

इन सभी मामलों और अन्य मामलों में, समस्या की वजह का पता लगाने के लिए सबसे पहले, गड़बड़ी वाले जवाब की जानकारी की जांच करें.

जवाबों को पार्स करना

डिफ़ॉल्ट रूप से, Google Ads स्क्रिप्ट इंजन, गड़बड़ी (400 या उससे ज़्यादा का स्टेटस कोड) दिखाने वाले किसी भी जवाब को दिखाएगा.

इस तरह की गड़बड़ी से बचने और गड़बड़ी और गड़बड़ी के मैसेज की जांच करने की अनुमति देने के लिए, वैकल्पिक पैरामीटर की muteHttpExceptions प्रॉपर्टी को UrlFetchApp.fetch पर सेट करें. उदाहरण के लिए:

const params = {
  muteHttpExceptions: true
};
const response = UrlFetchApp.fetch(url, params);
if (response.getResponseCode() >= 400) {
  // ... inspect error details...
}

सामान्य स्टेटस कोड

  • 200 OK, सफलता का संकेत देता है. अगर जवाब में उम्मीद के मुताबिक डेटा नहीं है, तो इन बातों का ध्यान रखें:

    • कुछ एपीआई, यह तय करने की अनुमति देते हैं कि किन फ़ील्ड और/या रिस्पॉन्स फ़ॉर्मैट का इस्तेमाल करना है. इस बारे में ज़्यादा जानने के लिए, एपीआई दस्तावेज़ देखें.
    • किसी एपीआई में ऐसे कई संसाधन हो सकते हैं जिन्हें कॉल किया जा सकता है. दस्तावेज़ देखकर पता लगाएं कि क्या कोई दूसरा रिसॉर्स इस्तेमाल करना ज़्यादा सही होगा और वह आपके काम का डेटा देगा या नहीं.
    • कोड लिखे जाने के बाद, एपीआई में बदलाव हो सकता है. ज़्यादा जानकारी के लिए, दस्तावेज़ देखें या डेवलपर से संपर्क करें.

  • आम तौर पर, 400 Bad Request का मतलब है कि सर्वर को भेजे गए अनुरोध के फ़ॉर्मैट या स्ट्रक्चर में कुछ गड़बड़ी है. अनुरोध की जांच करें और उसकी तुलना एपीआई की खास बातों से करें, ताकि यह पक्का किया जा सके कि वह उम्मीदों के मुताबिक है. अनुरोधों की जांच करने का तरीका जानने के लिए, अनुरोधों की जांच करना लेख पढ़ें.

  • आम तौर पर, 401 Unauthorized का मतलब है कि एपीआई को अनुमति दिए बिना या अनुमति मिलने के बाद भी कॉल किया जा रहा है.

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

  • 403 Forbidden से पता चलता है कि उपयोगकर्ता के पास उस संसाधन के लिए अनुमति नहीं है जिसके लिए अनुरोध किया जा रहा है.

    • पक्का करें कि उपयोगकर्ता को ज़रूरी अनुमतियां दी गई हों. उदाहरण के लिए, फ़ाइल पर आधारित अनुरोध में उपयोगकर्ता को फ़ाइल का ऐक्सेस देना.

  • 404 Not Found का मतलब है कि अनुरोध किया गया संसाधन मौजूद नहीं है.

    • देखें कि एपीआई एंडपॉइंट के लिए इस्तेमाल किया गया यूआरएल सही है या नहीं.
    • किसी संसाधन को फ़ेच करते समय, देखें कि जिस संसाधन का रेफ़रंस दिया जा रहा है वह मौजूद है या नहीं. उदाहरण के लिए, फ़ाइल-आधारित एपीआई के लिए फ़ाइल मौजूद है या नहीं.

अनुरोधों की जांच करना

अनुरोधों की जांच करना तब फ़ायदेमंद होता है, जब एपीआई के जवाबों से पता चलता है कि अनुरोध गलत तरीके से बनाया गया है. उदाहरण के लिए, 400 स्टेटस कोड. अनुरोधों की जांच करने में मदद करने के लिए, UrlFetchApp के पास fetch() के तरीके के साथ-साथ एक और तरीका है. इसे getRequest() कहा जाता है

यह तरीका, सर्वर को अनुरोध भेजने के बजाय, वह अनुरोध बनाता है जो भेजा गया होता. इसके बाद, वह अनुरोध दिखाता है. इससे उपयोगकर्ता, अनुरोध के एलिमेंट की जांच कर सकता है, ताकि यह पक्का किया जा सके कि अनुरोध सही है.

उदाहरण के लिए, अगर आपके अनुरोध में फ़ॉर्म डेटा में कई स्ट्रिंग एक साथ जोड़ी गई हैं, तो हो सकता है कि गड़बड़ी उस फ़ंक्शन में हो जिसे आपने फ़ॉर्म डेटा जनरेट करने के लिए बनाया था. आसान शब्दों में:

const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...

की मदद से, अनुरोध के एलिमेंट की जांच की जा सकती है.

अनुरोध और जवाबों को लॉग करना

तीसरे पक्ष के एपीआई के अनुरोधों और जवाबों की जांच करने की पूरी प्रोसेस में मदद करने के लिए, यहां दिए गए हेल्पर फ़ंक्शन का इस्तेमाल किया जा सकता है. इसे UrlFetchApp.fetch() के लिए ड्रॉप-इन रिप्लेसमेंट के तौर पर इस्तेमाल किया जा सकता है, ताकि अनुरोध और जवाब, दोनों को लॉग किया जा सके.

  1. अपने कोड में UrlFetchApp.fetch() के सभी इंस्टेंस को logUrlFetch() से बदलें.

  2. अपनी स्क्रिप्ट के आखिर में यह फ़ंक्शन जोड़ें.

    function logUrlFetch(url, opt_params) {
  const params = opt_params || {};
  params.muteHttpExceptions = true;
  const request = UrlFetchApp.getRequest(url, params);
  console.log('Request:       >>> ' + JSON.stringify(request));
  const response = UrlFetchApp.fetch(url, params);
  console.log('Response Code: <<< ' + response.getResponseCode());
  console.log('Response text: <<< ' + response.getContentText());
  if (response.getResponseCode() >= 400) {
    throw Error('Error in response: ' + response);
  }
  return response;
}

स्क्रिप्ट को लागू करते समय, सभी अनुरोधों और जवाबों की जानकारी को कंसोल में लॉग किया जाता है. इससे, डीबग करने में आसानी होती है.