तृतीय-पक्ष API

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

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

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

ध्यान दें: तीसरे पक्ष के एपीआई का इस्तेमाल करने वाली स्क्रिप्ट को लिखित रूप में या इस्तेमाल करने के लिए इस्तेमाल करें. हमारा सुझाव है कि आप एपीआई से जुड़े नियम और शर्तों को पढ़ें, ताकि यह पक्का किया जा सके कि उनका इस्तेमाल उन नियमों और शर्तों के मुताबिक है.

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

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 स्ट्रिंग को बदलने के लिए, पहले से मौजूद JSON.parse तरीके का इस्तेमाल करें. जैसे, OpenWeatherMap से मिली JSON स्ट्रिंग को वापस JavaScript ऑब्जेक्ट में बदलने के लिए. ऊपर दिए गए उदाहरण से जारी रखा गया है:

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 तरीके का इस्तेमाल करते हैं.

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

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

Slack सेट अप करना

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

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

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

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 के फ़ॉर्मैट के हिसाब से, POST अनुरोध को बनाने के लिए UrlFetchApp अलग-अलग तरीके अपनाता है:

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

• जब payload कोई ऑब्जेक्ट हो, उदाहरण के लिए, वैल्यू का मैप:

  {to: '[e-mail]', subject:'Test', body:'Hello, World!'}
  

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

  subject=Test&to=[e-mail]&body=Hello,+World!
  

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

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

एचटीटीपी के ज़रिए पुष्टि करने की बुनियादी जानकारी

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

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

अनुरोध करें

पुष्टि किया गया अनुरोध करने के लिए, इन चरणों को पूरा करना ज़रूरी है:

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

नीचे दिए गए स्निपेट में 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 के नाम से जाना जाता है.

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);

ध्यान दें: Google Ads स्क्रिप्ट कुछ समय के लिए ही काम करती हैं. इसलिए, इस सैंपल लाइब्रेरी में ऐक्सेस टोकन को रीफ़्रेश करने की कोई कोशिश नहीं की जाती है.

क्लाइंट क्रेडेंशियल की अनुमति

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

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

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

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

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

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

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 स्क्रिप्ट एक्ज़िक्यूशन एपीआई का उदाहरण

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

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. एपीआई कंसोल पर जाने के लिए, प्रोजेक्ट के नाम पर क्लिक करें.
4. एपीआई और सेवाएं पर जाएं.
5. सही एपीआई चालू करें. उदाहरण के लिए, Drive API, और Apps Script Execution एपीआई.
6. मेन्यू में मौजूद क्रेडेंशियल आइटम से OAuth क्रेडेंशियल बनाएं.
7. अपनी स्क्रिप्ट पर वापस जाकर, पब्लिश करें > एपीआई एक्ज़ीक्यूटेबल के तौर पर डिप्लॉय करें पर जाकर, स्क्रिप्ट को पब्लिश करें.

Google Ads स्क्रिप्ट बनाना

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

सेवा वाले खाते

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

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

Google नैचुरल लैंग्वेज एपीआई का उदाहरण

Natural Language API में, टेक्स्ट के लिए भावों का विश्लेषण और इकाई का विश्लेषण किया जाता है.

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

स्क्रिप्ट सेट अप करें

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

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

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

JSON

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

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

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

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() का इस्तेमाल करें और हर बच्चे के हिसाब से दोहराने के बारे में सोचें जिनमें कई टेक्स्ट वाले बच्चों की संभावना हो.

स्पोर्ट बादर का उदाहरण

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

Sportradar खाता सेट अप करें

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

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

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

एक बार सफलता मिल जाने पर, उस पेज पर आपकी नई एपीआई कुंजी वाला पेज दिखेगा.

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

समस्या हल करना

तीसरे पक्ष के एपीआई के साथ काम करते समय, गड़बड़ियां कई वजहों से हो सकती हैं, जैसे:

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

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

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

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

ऐसे व्यवहार को रोकने और गड़बड़ी और गड़बड़ी के मैसेज की जांच करने के लिए, वैकल्पिक पैरामीटर की 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;
   }
   

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