तृतीय-पक्ष API

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

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

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

हमने यह भी शामिल किया है: किसी संख्या के लिए सैंपल जो इन सिद्धांतों को दिखाते हैं.

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

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

नीचे दिए गए उदाहरण में, यहां से मौसम का डेटा फ़ेच करने का तरीका दिखाया गया है OpenWeatherMap. हमने OpenWeathermap इसलिए चुना, क्योंकि पुष्टि करने की यह स्कीम और एपीआई है.

अनुरोध करें

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

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

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

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

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

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

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

JSON डेटा

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

किसी JSON स्ट्रिंग को बदलने के लिए—जैसे कि स्ट्रिंग को OpenWeatherMap—वापस एक JavaScript ऑब्जेक्ट में, बिल्टइन का इस्तेमाल करें JSON.parse तरीका. ऊपर दिए गए उदाहरण से आगे क्या ���ोगा:

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

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

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

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

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

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

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

उम्मीद के मुताबिक जवाब मिलने की संभावना को देखते हुए, आपको HTTP स्टेटस कोड. डिफ़ॉल्ट रूप से, अगर एचटीटीपी गड़बड़ी कोड मिलता है, तो 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();
}

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

जब तीसरे पक्ष के एपीआई बदलते हैं, तो अक्सर डेवलपर को इसकी तुरंत जानकारी नहीं होती है स्क्रिप्ट पर असर डाल सकते हैं. उदाहरण के लिए, अगर name प्रॉपर्टी OpenWeatherMap उदाहरण में वापस लौटाए गए हों, जिसे स्क्रिप्ट में 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 है. हालांकि, कुछ API कॉल, जैसे, मैसेज (एसएमएस) भेजने वाली सेवा को कॉल करने के लिए दूसरे तरीकों की ज़रूरत होगी, जैसे कि POST या PUT.

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

Slack सेट अप करें

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

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

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

पीओएसटी अनुरोध करें

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

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

Extended Slack का उदाहरण

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

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

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

फ़ॉर्म डेटा

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

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

  • जब payload एक स्ट्रिंग होती है, तो स्ट्रिंग तर्क इस फ़ॉर्मैट में भेजा जाता है: अनुरोध का मुख्य हिस्सा.

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

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

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

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

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

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

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

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

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

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

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

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

  1. उपयोगकर्ता नाम और पासवर��ड को एक साथ मिलाकर लंबा पासवर्ड बनाएं कोलन, उदाहरण के लिए username:password.
  2. Base64, लंबा पासवर्ड को एन्कोड करता है. उदाहरण के लिए, username:password dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. अनुरोध के साथ Authorization: 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 स्क्रिप्ट की ज़रूरत होगी) चरण 1,2 और 3 संभव नहीं हैं. इसलिए, कुछ सेवाएं अपने कॉन्फ़िगरेशन से ऐक्सेस टोकन जारी करती हैं इससे ऐप्लिकेशन सीधे चौथे चरण पर जा सकेगा. इसे इस नाम से जाना जाता है: एक पैरों वाले OAuth 1.0.

OAuth1

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

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

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

OAuth 2.0

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

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

Google Ads स्क्रिप्ट में OAuth 2.0 की सुविधा वाली सेवाओं का इस्तेमाल करने के लिए, कई कदम:

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

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

यह तय करना होता है कि Google Ads स्क्रिप्ट ऐप्लिकेशन को ऐक्सेस के कौनसे अधिकार होने चाहिए दिया गया है और इसे आम तौर पर एक Client-ID असाइन किया जाएगा. इससे आपको, OAuth 2 का इस्तेमाल करके यह कंट्रोल किया जा सकता है कि कौनसे ऐप्लिकेशन आपके डेटा को ऐक्सेस कर सकते हैं और यह भी कि वे उस डेटा के कौनसे पहलू देख सकती हैं या बदलें.

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

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

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

ऑथराइज़ेशन फ़्लो

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

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

लागू करना

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

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

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

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

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

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

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

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

टोकन ऐक्सेस करने की अनुमति को रीफ़्रेश करें

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

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

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

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

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

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

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

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

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

OAuth प्लेग्राउंड

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

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

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

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

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

Search Ads 360 का उदाहरण

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

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

Apps Script एक्ज़ीक्यूशन एपीआई का उदाहरण

इस उदाहरण में, ऐप्लिकेशन स्क्रिप्ट एक्ज़ीक्यूशन एपीआई. इससे Apps Script को कॉल के लिए इस्तेमाल किया जा सकता है.

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

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

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

सेवा खाते

ऊपर दिए गए अनुदान के विकल्प का विकल्प सेवा खाते हैं.

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

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

नैचुरल लैंग्वेज एपीआई भावना विश्लेषण और इकाई लेख के लिए विश्लेषण.

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

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

एपीआई से मिले जवाब

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

JSON

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

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

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

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

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

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

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

XML

पुष्टि

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

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

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

रूट एलिमेंट

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

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

नाम स्थान

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

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

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

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

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

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

वैल्यू पाएं

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

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

एट्रिब्यूट को फिर से हासिल किया जा सकता है, उदाहरण के लिए:

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

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

स्पोर्टराडार उदाहरण

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

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

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

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

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