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 ऑब्जेक्ट के सीरियलाइज़ेशन को दिखाता है. इससे ऑब्जेक्ट, कलेक्शन, और बुनियादी टाइप को स्ट्रिंग के तौर पर दिखाया और ट्रांसफ़र किया जा सकता है.
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 की मदद से डेटा पोस्ट करना
OpenWeatherMap के साथ शुरुआती उदाहरण में सिर्फ़ डेटा फ़ेच किया गया. आम तौर पर, रिमोट सर्वर पर स्थिति में बदलाव न करने वाले एपीआई कॉल, HTTP
GET तरीके का इस्तेमाल करते हैं.
UrlFetchApp के लिए, GET तरीका डिफ़ॉल्ट रूप से सेट होता है. हालांकि, कुछ एपीआई कॉल के लिए, अन्य तरीकों की ज़रूरत होगी. जैसे, POST या PUT. जैसे, एसएमएस भेजने वाली सेवा को किए जाने वाले कॉल.
UrlFetchApp के साथ POST कॉल इस्तेमाल करने का तरीका बताने के लिए, यहां दिए गए उदाहरण में Slack के साथ इंटिग्रेशन दिखाया गया है. Slack, साथ मिलकर काम करने के लिए इस्तेमाल किया जाने वाला एक मैसेजिंग ऐप्लिकेशन है. इसका इस्तेमाल, Slack के उपयोगकर्ताओं और ग्रुप को Slack मैसेज भेजने के लिए किया जाता है.
Slack को सेट अप करें
हम उम्मीद करते हैं कि आपने Slack खाते के लिए पहले ही साइन अप कर लिया होगा.
पिछले उदाहरण में OpenWeatherMap की तरह, मैसेज भेजने की सुविधा चालू करने के लिए टोकन पाना ज़रूरी है. Slack आपको एक यूनीक यूआरएल देता है, ताकि आप अपनी टीम को मैसेज भेज सकें. इसे इनकमिंग वेबहुक कहा जाता है.
इनकमिंग वेबहुक इंटिग्रेशन जोड़ें पर क्लिक करके, इनकमिंग वेबहुक सेट अप करें और निर्देशों का पालन करें. इस प्रोसेस के बाद, मैसेज भेजने के लिए एक यूआरएल जारी किया जाना चाहिए.
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 कहा जाता है.

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 के इस्तेमाल की अनुमति का हर टाइप और उससे जुड़ा फ़्लो, इस्तेमाल के अलग-अलग मामलों के लिए काम करता है. उदाहरण के लिए, जब कोई उपयोगकर्ता किसी इंटरैक्टिव सेशन में हिस्सा लेता है, तो एक अलग फ़्लो का इस्तेमाल किया जाता है. इसके उलट, जब किसी ऐप्लिकेशन को उपयोगकर्ता की मौजूदगी के बिना बैकग्राउंड में चलाना ज़रूरी होता है, तो एक अलग फ़्लो का इस्तेमाल किया जाता है.
एपीआई उपलब्ध कराने वाली कंपनियां यह तय करेंगी कि वे OAuth के इस्तेमाल की अनुमति के किस टाइप को स्वीकार करेंगी. इससे उपयोगकर्ता को यह समझने में मदद मिलेगी कि उन्हें अपने एपीआई को कैसे इंटिग्रेट करना है.
लागू करना
सभी अलग-अलग 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 playground एक यूज़र इंटरफ़ेस (यूआई) उपलब्ध कराता है. इसकी मदद से, उपयोगकर्ता ऑथराइज़ेशन कोड की अनुमति पाकर, रीफ़्रेश टोकन हासिल कर सकता है.
सबसे ऊपर दाईं ओर मौजूद सेटिंग बटन की मदद से, 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 क्रेडेंशियल बनाएं.
- अपनी स्क्रिप्ट पर वापस जाएं. इसके बाद, पब्लिश करें > एपीआई के तौर पर डिप्लॉय करें पर जाकर, स्क्रिप्ट को पब्लिश करें.
Google Ads स्क्रिप्ट बनाना
- सैंपल स्क्रिप्ट को Google Ads में नई स्क्रिप्ट में चिपकाएं.
- इसके अलावा, कोड लिस्टिंग के नीचे [सैंपल OAuth2 लाइब्रेरी][oauth20-library-example] चिपकाएं.
- स्क्रिप्ट में बदलाव करें, ताकि उसमें क्लाइंट आईडी, क्लाइंट सीक्रेट, और रीफ़्रेश टोकन की सही वैल्यू शामिल हों.
सेवा खाते
OAuth के इस्तेमाल की अनुमति के टाइप का एक विकल्प, सेवा खातों का कॉन्सेप्ट है.
सेवा खाते, OAuth के इस्तेमाल की अनुमति के टाइप से अलग होते हैं. ऐसा इसलिए, क्योंकि इनका इस्तेमाल उपयोगकर्ता का डेटा ऐक्सेस करने के लिए नहीं किया जाता: पुष्टि होने के बाद, सेवा खाता ऐप्लिकेशन की ओर से अनुरोध करता है, न कि उस उपयोगकर्ता के तौर पर जो प्रोजेक्ट का मालिक हो सकता है. उदाहरण के लिए, अगर सेवा खाता, फ़ाइल बनाने के लिए Drive API का इस्तेमाल करता है, तो यह सेवा खाते से जुड़ी होगी. साथ ही, डिफ़ॉल्ट रूप से प्रोजेक्ट का मालिक इसे ऐक्सेस नहीं कर पाएगा.
Google नैचुरल लैंग्वेज एपीआई का उदाहरण
[नैचुरल लैंग्वेज एपीआई][natural-language-api-docs], टेक्स्ट के लिए [भावनाओं का विश्लेषण][sentiment-analysis-api-docs] और [इकाई का विश्लेषण][entity-analysis-api-docs] उपलब्ध कराता है.
इस उदाहरण में, विज्ञापन टेक्स्ट के लिए [भावना][sentiment-api-docs] का हिसाब लगाने का तरीका बताया गया है. इसमें हेडलाइन या ब्यौरा शामिल है. इससे पता चलता है कि मैसेज कितना पॉज़िटिव है और उसका असर कितना है: इनमें से कौनसा बेहतर है, हम केक बेचते हैं या हम लंदन में सबसे अच्छे केक बेचते हैं. आज ही खरीदें!?
स्क्रिप्ट सेट अप करना
- Google Cloud Console में एक नया प्रोजेक्ट बनाएं.
- [नैचुरल लैंग्वेज 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को खत्म होगा.
एपीआई से मिली जानकारी
एपीआई, डेटा को कई फ़ॉर्मैट में दिखा सकते हैं. इनमें से सबसे ज़्यादा इस्तेमाल होने वाले फ़ॉर्मैट, एक्सएमएल और 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 की मदद से, आपकी स्क्रिप्ट एक्सएमएल रिस्पॉन्स बॉडी से डेटा को पार्स और एक्सट्रैक्ट कर सकती हैं.
पुष्टि
एपीआई बनाने के लिए, एक्सएमएल अब भी एक लोकप्रिय फ़ॉर्मैट है. एपीआई कॉल से मिले जवाब को 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, अलग-अलग खेलों को अलग-अलग एपीआई में बांटता है. उदाहरण के लिए, हो सकता है कि आपने सॉकर एपीआई का ऐक्सेस खरीदा हो, लेकिन टेनिस एपीआई का नहीं. आपके बनाए गए हर ऐप्लिकेशन में, अलग-अलग खेल और अलग-अलग कुंजियां हो सकती हैं.
- Applications में जाकर, Create a new Application पर क्लिक करें. ऐप्लिकेशन को कोई नाम और ब्यौरा दें. साथ ही, वेबसाइट फ़ील्ड को अनदेखा करें.
- सिर्फ़ Issue a new key for Soccer Trial Europe v2 को चुनें.
- Register Application पर क्लिक करें.
इसके बाद, आपको एक पेज दिखेगा, जिस पर आपका नया एपीआई पासकोड मौजूद होगा.
- सैंपल स्क्रिप्ट को 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 का इस्तेमाल करता है, तो पक्का करें कि ऐक्सेस टोकन मिल गया हो और उसे धारक टोकन के तौर पर दिया जा रहा हो.
- अनुमति देने के किसी भी अन्य तरीके के लिए, पक्का करें कि अनुरोध के लिए ज़रूरी क्रेडेंशियल दिए जा रहे हों.
- अगर एपीआई, अनुमति देने के लिए बुनियादी तरीके का इस्तेमाल करता है, तो पक्का करें कि अनुरोध में
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