Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

तृतीय-पक्ष API

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

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

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

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

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 ऑब्जेक्ट का सीरियलाइज़ेशन दिखाता है, ताकि ऑब्जेक्ट, ऐरे, और बुनियादी टाइप को स्ट्रिंग के तौर पर दिखाया और ट्रांसफ़र किया जा सके.

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

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 की मदद से POST डेटा

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

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

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

Slack सेट अप करना

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

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

Add Incoming WebHooks Integration पर क्लिक करके और निर्देशों का पालन करके, Incoming Webhook सेट अप करें. इस प्रोसेस में, मैसेज भेजने के लिए एक यूआरएल जारी किया जाना चाहिए.

POST अनुरोध करना

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

method: जैसा कि बताया गया है, यह डिफ़ॉल्ट रूप से GET पर सेट होता है. हालांकि, यहां हम इसे बदलकर POST पर सेट करते हैं.
payload: यह वह डेटा है जिसे POST अनुरोध के हिस्से के तौर पर सर्वर को भेजा जाना है. इस उदाहरण में, Slack को JSON फ़ॉर्मैट में क्रम से लगाया गया ऑब्जेक्ट चाहिए. इसके बारे में Slack के दस्तावेज़ में बताया गया है. इसके लिए, [JSON.stringify][json-stringify-url] तरीके का इस्तेमाल किया जाता है. साथ ही, 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 पर सेट किया जाता है.

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

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

एचटीटीपी बेसिक ऑथेंटिकेशन, पुष्टि करने का सबसे आसान तरीका है. इसका इस्तेमाल कई एपीआई करते हैं.

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

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

अनुरोध तैयार करना

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

उपयोगकर्ता नाम और पासवर्ड को कोलन के साथ जोड़कर पासफ़्रेज़ बनाएं. उदाहरण के लिए, username:password.
पासफ़्रेज़ को Base64 कोड में बदलें. उदाहरण के लिए, username:password को dXNlcm5hbWU6cGFzc3dvcmQ= में बदलें.
अनुरोध में 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 एक ऐसी सेवा है जो अपने एपीआई की मदद से, एसएमएस मैसेज भेजने और पाने की सुविधा देती है. इस सैंपल में, मैसेज भेजने का तरीका बताया गया है.

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

Twilio

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

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

OAuth 1.0

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

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

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

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

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

अपनी स्क्रिप्ट में

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

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

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

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

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

लागू करना

सभी 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);

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

[क्लाइंट क्रेडेंशियल ग्रांट][client-credentials-rfc], 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

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

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

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

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

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

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

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

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

सबसे ऊपर दाईं ओर मौजूद सेटिंग बटन की मदद से, 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 का रेफ़रंस देखें.

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

Google Cloud Console में एक नया प्रोजेक्ट बनाएं. साथ ही, Search Ads 360 की गाइड में दी गई प्रक्रिया का पालन करके, क्लाइंट आईडी, क्लाइंट सीक्रेट, और रीफ़्रेश टोकन पाएं. यह पक्का करें कि आपने Search Ads 360 API चालू किया हो.
[सैंपल स्क्रिप्ट][search-ads-360-example] को Google Ads में नई स्क्रिप्ट में चिपकाएं.
कोड लिस्टिंग के नीचे, [OAuth2 लाइब्रेरी का सैंपल][oauth20-library-example] चिपकाएं.
स्क्रिप्ट में बदलाव करके, क्लाइंट आईडी, क्लाइंट सीक्रेट, और रीफ़्रेश टोकन की सही वैल्यू शामिल करें.

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 को लागू करने के लिए कॉन्फ़िगर करना

स्क्रिप्ट सेव करें.
संसाधन > Cloud Platform प्रोजेक्ट पर क्लिक करें.
Google Cloud Console पर जाने के लिए, प्रोजेक्ट के नाम पर क्लिक करें.
एपीआई और सेवाएं पर जाएं.
ज़रूरी एपीआई चालू करें. इस मामले में, Drive API और Apps Script Execution API को चालू करें.
मेन्यू में मौजूद क्रेडेंशियल आइटम से, OAuth क्रेडेंशियल बनाएं.
अपनी स्क्रिप्ट में वापस जाएं और स्क्रिप्ट को एक्ज़ीक्यूट करने के लिए, पब्लिश करें > API एक्ज़ीक्यूटेबल के तौर पर डिप्लॉय करें पर क्लिक करें.

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

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

सेवा खाते

अनुमति देने के टाइप के अलावा, सेवा खातों का इस्तेमाल किया जा सकता है.

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

Google नैचुरल लैंग्वेज API का उदाहरण

[नैचुरल लैंग्वेज एपीआई][natural-language-api-docs] टेक्स्ट के लिए, [भावनाओं का विश्लेषण][sentiment-analysis-api-docs] और [इकाई का विश्लेषण][entity-analysis-api-docs] करता है.

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

स्क्रिप्ट सेट अप करना

Google Cloud Console में एक नया प्रोजेक्ट बनाएं.
[Natural Language API][natural-language-api] को चालू करें.
प्रोजेक्ट के लिए बिलिंग चालू करें.
[सेवा खाता बनाएं][create-service-account]. क्रेडेंशियल वाली JSON फ़ाइल डाउनलोड करें.
[सैंपल स्क्रिप्ट][natural-language-example] को Google Ads में नई स्क्रिप्ट में चिपकाएं.
इसके अलावा, कोड लिस्टिंग के नीचे [OAuth2 लाइब्रेरी का सैंपल][oauth20-library-example] चिपकाएं.
ज़रूरी वैल्यू बदलें:
- serviceAccount: सेवा खाते का ईमेल पता. उदाहरण के लिए, xxxxx@yyyy.iam.gserviceaccount.com.
- key: यह सेवा खाता बनाते समय डाउनलोड की गई JSON फ़ाइल की कुंजी होती है. -----BEGIN PRIVATE KEY... बजे शुरू होता है और ...END PRIVATE KEY-----\n बजे खत्म होता है.

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

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

JSON

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

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

एपीआई कॉल से जवाब मिलने के बाद, अगला चरण आम तौर पर 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 की मदद से, आपकी स्क्रिप्ट, एक्सएमएल रिस्पॉन्स बॉडी से डेटा को पार्स और एक्सट्रैक्ट कर सकती हैं.

पुष्टि

एपीआई बनाने के लिए, एक्सएमएल अब भी एक लोकप्रिय फ़ॉर्मैट है. एपीआई कॉल से मिले जवाब को 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_schedules xmlns="http://schemas.sportradar.com/sportsapi/soccer/v4">
  <schedule>
     ...
  </schedule>
</schedule_schedules>

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

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

यहां दिए गए सैंपल में, <schedule> एलिमेंट को ऐक्सेस करने और दस्तावेज़ के पिछले स्निपेट में इसके <sport_event> चाइल्ड एलिमेंट खोजने का तरीका बताया गया है:

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

वैल्यू पाना

सॉकर के शेड्यूल के इस उदाहरण को देखें:

<sport_event_status status="..." ... />

एट्रिब्यूट को इस तरह से वापस पाया जा सकता है, जैसे कि:

const statusElement = sportEventElement.getChild('sport_event_status', namespace);
const status = statusElement.getAttribute('status').getValue();

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

Sportradar का उदाहरण

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

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

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

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

ऐप्लिकेशन में जाकर, नया ऐप्लिकेशन बनाएं पर क्लिक करें. ऐप्लिकेशन को कोई नाम दें और उसके बारे में जानकारी दें. साथ ही, वेबसाइट फ़ील्ड को अनदेखा करें.
सिर्फ़ Issue a new key for Soccer Trial Europe v2 को चुनें.
ऐप्लिकेशन रजिस्टर करें पर क्लिक करें.

यह प्रोसेस पूरी होने के बाद, आपको एक ऐसा पेज दिखेगा जिस पर आपका नया एपीआई पासकोड मौजूद होगा.

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

समस्या का हल

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

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

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

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

डिफ़ॉल्ट रूप से, गड़बड़ी (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 का इस्तेमाल करता है, तो पक्का करें कि ऐक्सेस टोकन हासिल कर लिया गया हो और उसे Bearer टोकन के तौर पर दिया जा रहा हो.
- अनुमति से जुड़े किसी अन्य बदलाव के लिए, पक्का करें कि अनुरोध के लिए ज़रूरी क्रेडेंशियल दिए जा रहे हों.
403 Forbidden से पता चलता है कि उपयोगकर्ता के पास उस संसाधन का ऐक्सेस नहीं है जिसके लिए अनुरोध किया गया है.
- पक्का करें कि उपयोगकर्ता को ज़रूरी अनुमतियां दी गई हों. उदाहरण के लिए, फ़ाइल पर आधारित अनुरोध में उपयोगकर्ता को किसी फ़ाइल का ऐक्सेस देना.
404 Not Found का मतलब है कि अनुरोध किया गया संसाधन मौजूद नहीं है.
- देख लें कि एपीआई एंडपॉइंट के लिए इस्तेमाल किया गया यूआरएल सही हो.
- अगर किसी संसाधन को फ़ेच किया जा रहा है, तो पक्का करें कि जिस संसाधन का रेफ़रंस दिया गया है वह मौजूद हो. उदाहरण के लिए, अगर फ़ाइल पर आधारित एपीआई के लिए फ़ाइल मौजूद है.

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

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

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

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

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

इससे, अनुरोध के एलिमेंट की जांच की जा सकेगी.

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

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

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

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

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

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

[json-stringify-url]: //developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [client-credentials-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-4.4 [authorization-code-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 [oauth20-library-example]: /google-ads/scripts/docs/examples/oauth20-library [search-ads-360-example]: /google-ads/scripts/docs/examples/search-ads-360 [natural-language-api]: //console.developers.google.com/apis/api/language.googleapis.com/overview [create-service-account]: //console.developers.google.com/apis/credentials/serviceaccountkey [natural-language-example]: /google-ads/scripts/docs/examples/natural-language [natural-language-api-docs]: //cloud.google.com/natural-language/docs/ [sentiment-api-docs]: //cloud.google.com/natural-language/docs/reference/rest/v1beta2/Sentiment [sentiment-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-sentiment [entity-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-entities