তৃতীয় পক্ষের API

গুগল অ্যাডস স্ক্রিপ্টের একটি শক্তিশালী বৈশিষ্ট্য হলো থার্ড-পার্টি এপিআই (API) থেকে ডেটা এবং পরিষেবাগুলোর সাথে ইন্টিগ্রেট করার ক্ষমতা।

এই নির্দেশিকাটিতে নিম্নলিখিত ধারণাগুলি আলোচনা করা হয়েছে যা আপনাকে অন্যান্য পরিষেবার সাথে সংযোগ স্থাপনের জন্য স্ক্রিপ্ট লিখতে সাহায্য করতে পারে:

  • HTTP অনুরোধ করা : বাহ্যিক API অ্যাক্সেস করতে কীভাবে UrlFetchApp ব্যবহার করবেন।
  • প্রমাণীকরণ : আমরা প্রমাণীকরণের কিছু সাধারণ পরিস্থিতি নিয়ে আলোচনা করব।
  • প্রতিক্রিয়া পার্সিং : ফেরত আসা JSON এবং XML ডেটা কীভাবে প্রসেস করবেন।

এই ধারণাগুলো ব্যাখ্যা করার জন্য আমরা বেশ কিছু জনপ্রিয় এপিআই-এর নমুনাও অন্তর্ভুক্ত করেছি।

UrlFetchApp দিয়ে ডেটা আনুন

UrlFetchApp তৃতীয় পক্ষের এপিআই-এর সাথে যোগাযোগের জন্য প্রয়োজনীয় মূল কার্যকারিতা প্রদান করে।

নিম্নলিখিত উদাহরণটি ওপেনওয়েদারম্যাপ থেকে আবহাওয়ার ডেটা সংগ্রহ করার পদ্ধতি দেখাচ্ছে। আমরা এর তুলনামূলকভাবে সহজ অনুমোদন ব্যবস্থা এবং এপিআই-এর কারণে ওপেনওয়েদারম্যাপ বেছে নিয়েছি।

একটি অনুরোধ করুন

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 টেক্সট স্ট্রিং লেখা হয়।

পরবর্তী ধাপ হলো এটিকে এমন একটি ফরম্যাটে রূপান্তর করা যা আপনার স্ক্রিপ্টে ব্যবহার করা যাবে।

JSON ডেটা

অনেক এপিআই JSON ফরম্যাটে প্রতিক্রিয়া প্রদান করে। এটি জাভাস্ক্রিপ্ট অবজেক্টের একটি সিরিয়ালাইজেশন, যার মাধ্যমে অবজেক্ট, অ্যারে এবং মৌলিক টাইপগুলোকে স্ট্রিং হিসেবে উপস্থাপন ও স্থানান্তর করা যায়।

OpenWeatherMap থেকে প্রাপ্ত JSON স্ট্রিং-এর মতো কোনো স্ট্রিংকে আবার জাভাস্ক্রিপ্ট অবজেক্টে রূপান্তর করতে, বিল্ট-ইন JSON.parse মেথডটি ব্যবহার করুন। আগের উদাহরণটির ধারাবাহিকতায়:

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

JSON.parse মেথডটি স্ট্রিংটিকে একটি অবজেক্টে রূপান্তর করে, যেটিতে `name` name একটি প্রপার্টি থাকে।

বিভিন্ন ফরম্যাটে থাকা এপিআই রেসপন্স নিয়ে কাজ করার বিষয়ে আরও বিস্তারিত জানতে ‘পার্স রেসপন্স’ সেকশনটি দেখুন।

ত্রুটি পরিচালনা

আপনার স্ক্রিপ্টে থার্ড-পার্টি এপিআই (API) নিয়ে কাজ করার সময় এরর হ্যান্ডলিং একটি গুরুত্বপূর্ণ বিষয়, কারণ থার্ড-পার্টি এপিআইগুলো প্রায়শই পরিবর্তিত হয় এবং অপ্রত্যাশিত রেসপন্স ভ্যালু তৈরি করে, যেমন:

  • আপনার অজান্তেই এপিআই-এর ইউআরএল বা প্যারামিটার পরিবর্তিত হতে পারে।
  • আপনার এপিআই কী (বা অন্যান্য ব্যবহারকারীর পরিচয়পত্র) মেয়াদোত্তীর্ণ হতে পারে।
  • প্রতিক্রিয়ার ধরণ পূর্ব বিজ্ঞপ্তি ছাড়াই পরিবর্তিত হতে পারে।

HTTP স্ট্যাটাস কোড

অপ্রত্যাশিত প্রতিক্রিয়ার সম্ভাবনার কারণে, আপনার HTTP স্ট্যাটাস কোডটি পরীক্ষা করা উচিত। ডিফল্টরূপে, কোনো 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();
}

প্রতিক্রিয়া কাঠামো

যখন থার্ড-পার্টি এপিআই পরিবর্তিত হয়, তখন এমন সব পরিবর্তন সম্পর্কে আপনি হয়তো তাৎক্ষণিকভাবে অবগত নাও হতে পারেন যা আপনার স্ক্রিপ্টগুলোকে প্রভাবিত করতে পারে। উদাহরণস্বরূপ, যদি 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-এর প্রাথমিক উদাহরণটি শুধুমাত্র ডেটা সংগ্রহ করেছিল। সাধারণত, যে API কলগুলো রিমোট সার্ভারের অবস্থার কোনো পরিবর্তন করে না, সেগুলো HTTP GET পদ্ধতি ব্যবহার করে।

UrlFetchApp এর জন্য GET মেথডটি হলো ডিফল্ট। তবে, কিছু API কল, যেমন SMS বার্তা প্রেরণকারী কোনো সার্ভিসে কল করার ক্ষেত্রে, POST বা PUT মতো অন্যান্য মেথডের প্রয়োজন হবে।

UrlFetchApp সাথে POST কল ব্যবহারের পদ্ধতি বোঝানোর জন্য, নিম্নলিখিত উদাহরণটিতে একটি সহযোগী মেসেজিং অ্যাপ্লিকেশন, স্ল্যাকের সাথে ইন্টিগ্রেশন দেখানো হয়েছে, যার মাধ্যমে স্ল্যাক ব্যবহারকারী এবং গ্রুপগুলিতে একটি স্ল্যাক মেসেজ পাঠানো হয়।

স্ল্যাক সেট আপ করুন

এই নির্দেশিকাটি ধরে নিচ্ছে যে আপনি ইতিমধ্যেই একটি স্ল্যাক অ্যাকাউন্ট খুলেছেন ।

আগের উদাহরণে OpenWeatherMap-এর মতোই, মেসেজ পাঠানো চালু করার জন্য একটি টোকেন সংগ্রহ করা প্রয়োজন। স্ল্যাক আপনার টিমকে মেসেজ পাঠানোর জন্য একটি অনন্য URL প্রদান করে, যাকে ইনকামিং ওয়েবহুক বলা হয়।

‘Add Incoming WebHooks Integration’- এ ক্লিক করে এবং নির্দেশাবলী অনুসরণ করে একটি ইনকামিং ওয়েবহুক সেট আপ করুন । এই প্রক্রিয়ার মাধ্যমে মেসেজিংয়ের জন্য একটি URL তৈরি হবে।

একটি POST অনুরোধ করুন

আপনার ইনকামিং ওয়েবহুক সেট আপ করার পরে, একটি POST অনুরোধ পাঠানোর জন্য UrlFetchApp.fetch এ পাস করা options প্যারামিটারে কিছু অতিরিক্ত প্রপার্টি ব্যবহার করতে হয়:

  • method : যেমনটি উল্লেখ করা হয়েছে, এটির ডিফল্ট মান হলো GET , কিন্তু এখানে আমরা এটিকে ওভাররাইড করে POST এ সেট করছি।

  • payload : এটি হলো সেই ডেটা যা POST রিকোয়েস্টের অংশ হিসেবে সার্ভারে পাঠানো হবে। এই উদাহরণে, স্ল্যাক তার ডকুমেন্টেশনে বর্ণিত JSON ফরম্যাটে সিরিয়ালাইজ করা একটি অবজেক্ট আশা করে। এর জন্য, 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);

বর্ধিত স্ল্যাক উদাহরণ

পূর্ববর্তী উদাহরণটি স্ল্যাকে ইনকামিং মেসেজ চালু করার জন্য প্রয়োজনীয় ন্যূনতম কোড দেখায়। একটি বিস্তারিত নমুনায় একটি গ্রুপে ক্যাম্পেইন পারফরম্যান্স রিপোর্ট তৈরি ও পাঠানোর পাশাপাশি কিছু ফরম্যাটিং এবং ডিসপ্লে অপশন তুলে ধরা হয়েছে।

আগত বার্তা

স্ল্যাক মেসেজ সম্পর্কে আরও বিস্তারিত জানতে স্ল্যাক ডকুমেন্টেশনে মেসেজ ফরম্যাটিং দেখুন।

ফর্ম ডেটা

পূর্ববর্তী উদাহরণে 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 হিসেবে সেট করা হয়েছে।

কিছু API-তে POST রিকোয়েস্ট সাবমিট করার সময় ফর্ম ডেটা ব্যবহারের প্রয়োজন হয়, তাই জাভাস্ক্রিপ্ট অবজেক্ট থেকে ফর্ম ডেটাতে এই স্বয়ংক্রিয় রূপান্তরের বিষয়টি মনে রাখা দরকারি।

HTTP বেসিক প্রমাণীকরণ

HTTP বেসিক অথেনটিকেশন হলো প্রমাণীকরণের অন্যতম সহজ একটি পদ্ধতি এবং এটি অনেক API-তে ব্যবহৃত হয়।

প্রতিটি অনুরোধের HTTP হেডারে একটি এনকোডেড ইউজারনেম এবং পাসওয়ার্ড সংযুক্ত করার মাধ্যমে প্রমাণীকরণ সম্পন্ন করা হয়।

HTTP বেসিক প্রমাণীকরণ

একটি অনুরোধ তৈরি করুন

একটি প্রমাণীকৃত অনুরোধ তৈরি করার জন্য নিম্নলিখিত পদক্ষেপগুলি প্রয়োজন:

  1. ইউজারনেম এবং পাসওয়ার্ডকে কোলন দিয়ে যুক্ত করে পাসফ্রেজটি তৈরি করুন, যেমন username:password ।
  2. পাসফ্রেজটিকে Base64 এনকোড করুন, উদাহরণস্বরূপ username:password হয়ে যাবে dXNlcm5hbWU6cGFzc3dvcmQ= ।
  3. অনুরোধের সাথে Authorization: Basic <encoded passphrase> এই ফর্মে একটি Authorization হেডার সংযুক্ত করুন।

নিম্নলিখিত কোড স্নিপেটটি দেখায় যে কীভাবে গুগল অ্যাডস স্ক্রিপ্টে এটি করা যায়:

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

মৌলিক প্রমাণীকরণ নমুনা

কোড স্যাম্পল বিভাগে দুটি স্যাম্পল রয়েছে যা HTTP বেসিক অথেনটিকেশন ব্যবহারের পদ্ধতি তুলে ধরে:

প্লিভো

প্লিভো একটি পরিষেবা যা তাদের এপিআই (API) ব্যবহার করে এসএমএস বার্তা পাঠানো এবং গ্রহণ করা সহজ করে। এই নমুনাটিতে বার্তা পাঠানোর পদ্ধতি দেখানো হয়েছে।

  1. Plivo- তে নিবন্ধন করুন।
  2. নমুনা স্ক্রিপ্টটি গুগল অ্যাডস-এর একটি নতুন স্ক্রিপ্টে পেস্ট করুন।
  3. ম্যানেজমেন্ট ড্যাশবোর্ড থেকে প্রাপ্ত মান দিয়ে PLIVO_ACCOUNT_AUTHID এবং PLIVO_ACCOUNT_AUTHTOKEN মানগুলি প্রতিস্থাপন করুন।
  4. ত্রুটির বিজ্ঞপ্তি পেতে স্ক্রিপ্টে উল্লেখিত স্থানে আপনার ইমেল ঠিকানাটি প্রবেশ করান।
  5. Plivo ব্যবহার করার জন্য, আপনাকে হয় নম্বর কিনতে হবে অথবা ট্রায়াল অ্যাকাউন্টে নম্বর যোগ করতে হবে। স্যান্ডবক্স নম্বর যোগ করুন যা ট্রায়াল অ্যাকাউন্টের সাথে ব্যবহার করা যাবে।
  6. প্রেরক হিসেবে প্রদর্শিত হবে এমন নম্বর এবং প্রাপকের নম্বর, উভয়ই যোগ করুন।
  7. স্ক্রিপ্টে থাকা PLIVO_SRC_PHONE_NUMBER সদ্য রেজিস্টার করা স্যান্ডবক্স নম্বরগুলোর মধ্যে একটি দিয়ে আপডেট করুন। এতে আন্তর্জাতিক কান্ট্রি কোড অন্তর্ভুক্ত থাকতে হবে, যেমন যুক্তরাজ্যের নম্বরের জন্য 447777123456 ।

টুইলিও

টুইলিও হলো আরেকটি পরিষেবা যা তাদের এপিআই (API) ব্যবহার করে এসএমএস বার্তা পাঠানো এবং গ্রহণ করার সুবিধা দেয়। এই নমুনাটিতে বার্তা পাঠানোর পদ্ধতি দেখানো হয়েছে।

  1. টুইলিও -তে নিবন্ধন করুন।
  2. নমুনা স্ক্রিপ্টটি গুগল অ্যাডস-এর একটি নতুন স্ক্রিপ্টে পেস্ট করুন।
  3. অ্যাকাউন্ট কনসোল পৃষ্ঠায় দেখানো মানগুলো দিয়ে TWILIO_ACCOUNT_SID এবং TWILIO_ACCOUNT_AUTHTOKEN মানগুলো প্রতিস্থাপন করুন।
  4. TWILIO_SRC_PHONE_NUMBER জায়গায় ড্যাশবোর্ড থেকে পাওয়া নম্বরটি বসান — এই নম্বরটি টুইলিও কর্তৃক বার্তা পাঠানোর জন্য অনুমোদিত।

OAuth 1.0

অনেক জনপ্রিয় পরিষেবা প্রমাণীকরণের জন্য OAuth ব্যবহার করে। OAuth-এর বিভিন্ন ধরন ও সংস্করণ রয়েছে।

যেখানে HTTP বেসিক অথেনটিকেশনের ক্ষেত্রে একজন ব্যবহারকারীর কেবল একটিই ইউজারনেম এবং পাসওয়ার্ড থাকে, সেখানে OAuth তৃতীয় পক্ষের অ্যাপ্লিকেশনগুলোকে সেই নির্দিষ্ট ক্রেডেনশিয়াল ব্যবহার করে ব্যবহারকারীর অ্যাকাউন্ট এবং ডেটাতে অ্যাক্সেস দেওয়ার অনুমতি দেয়। এছাড়াও, অ্যাক্সেসের পরিধিও সেই অ্যাপ্লিকেশনটির জন্যই নির্দিষ্ট হবে।

OAuth 1.0 সম্পর্কে পটভূমি জানতে, OAuth Core গাইডটি দেখুন। বিশেষ করে, ৬. OAuth দিয়ে প্রমাণীকরণ (6. Authenticating with OAuth ) অংশটি দেখুন। সম্পূর্ণ তিন-স্তরীয় OAuth 1.0-এ প্রক্রিয়াটি নিম্নরূপ:

  1. অ্যাপ্লিকেশনটি ("ভোক্তা") একটি অনুরোধ টোকেন সংগ্রহ করে।
  2. ব্যবহারকারী অনুরোধ টোকেনটি অনুমোদন করেন।
  3. অ্যাপ্লিকেশনটি রিকোয়েস্ট টোকেনটিকে একটি অ্যাক্সেস টোকেনে বিনিময় করে।
  4. পরবর্তী সকল রিসোর্স অনুরোধের জন্য , অ্যাক্সেস টোকেনটি একটি স্বাক্ষরিত অনুরোধে ব্যবহার করা হয়।

ব্যবহারকারীর হস্তক্ষেপ ছাড়া থার্ড-পার্টি সার্ভিসগুলোর OAuth 1.0 ব্যবহার করার ক্ষেত্রে (যেমনটা গুগল অ্যাডস স্ক্রিপ্টের জন্য প্রয়োজন হয়) ধাপ ১, ২ এবং ৩ সম্ভব নয়। একারণে, কিছু সার্ভিস তাদের কনফিগারেশন কনসোল থেকে একটি অ্যাক্সেস টোকেন ইস্যু করে, যা অ্যাপ্লিকেশনটিকে সরাসরি ধাপ ৪-এ যেতে দেয়। এটি ওয়ান-লেগড OAuth 1.0 নামে পরিচিত।

OAuth1

গুগল অ্যাডস স্ক্রিপ্টে OAuth 1.0

গুগল অ্যাডস স্ক্রিপ্টের ক্ষেত্রে, প্রতিটি স্ক্রিপ্টকে সাধারণত একটি অ্যাপ্লিকেশন হিসেবে গণ্য করা হয়। পরিষেবাটির কনসোল বা অ্যাডমিনিস্ট্রেশন সেটিংস পৃষ্ঠার মাধ্যমে সাধারণত নিম্নলিখিত কাজগুলো করা প্রয়োজন হয়:

  • স্ক্রিপ্টটি উপস্থাপন করার জন্য একটি অ্যাপ্লিকেশন কনফিগারেশন সেট আপ করুন।
  • স্ক্রিপ্টটিকে কী কী অনুমতি দেওয়া হচ্ছে তা নির্দিষ্ট করুন।
  • ওয়ান-লেগড OAuth-এর সাথে ব্যবহারের জন্য কনজিউমার কী, কনজিউমার সিক্রেট, অ্যাক্সেস টোকেন এবং অ্যাক্সেস সিক্রেট সংগ্রহ করুন।

OAuth 2.0

ব্যবহারকারীর ডেটাতে অ্যাক্সেস দেওয়ার জন্য জনপ্রিয় এপিআইগুলোতে OAuth 2.0 ব্যবহার করা হয়। কোনো নির্দিষ্ট থার্ড-পার্টি পরিষেবার অ্যাকাউন্টের মালিক নির্দিষ্ট অ্যাপ্লিকেশনগুলোকে ব্যবহারকারীর ডেটা অ্যাক্সেস করার অনুমতি দেন। এর সুবিধাগুলো হলো যে মালিক:

  • অ্যাপ্লিকেশনটির সাথে তাদের অ্যাকাউন্টের তথ্য শেয়ার করার প্রয়োজন নেই।
  • কোন অ্যাপ্লিকেশনগুলো ডেটা অ্যাক্সেস করতে পারবে এবং কী পরিমাণে পারবে, তা আলাদাভাবে নিয়ন্ত্রণ করা যায়। (উদাহরণস্বরূপ, প্রদত্ত অ্যাক্সেস শুধুমাত্র পড়ার জন্য হতে পারে, অথবা ডেটার একটি উপসেটের জন্য হতে পারে।)

গুগল অ্যাডস স্ক্রিপ্টে OAuth 2.0-সক্ষম পরিষেবা ব্যবহার করতে কয়েকটি ধাপ অনুসরণ করতে হয়:

আপনার স্ক্রিপ্টের বাইরে

তৃতীয় পক্ষের এপিআই (API)-এর মাধ্যমে আপনার ব্যবহারকারীর ডেটা অ্যাক্সেস করার জন্য গুগল অ্যাডস স্ক্রিপ্টকে অনুমোদন দিন । বেশিরভাগ ক্ষেত্রে এর জন্য তৃতীয় পক্ষের পরিষেবাটির কনসোলে একটি অ্যাপ্লিকেশন সেট আপ করতে হবে। এই অ্যাপ্লিকেশনটিই আপনার স্ক্রিপ্ট।

আপনি নির্দিষ্ট করে দেন যে গুগল অ্যাডস স্ক্রিপ্টস অ্যাপ্লিকেশনকে কী কী অ্যাক্সেস রাইটস দেওয়া হবে, এবং সাধারণত এটিকে একটি ক্লায়েন্ট আইডি বরাদ্দ করা হয়। এর মাধ্যমে আপনি OAuth 2.0 ব্যবহার করে নিয়ন্ত্রণ করতে পারেন যে, কোন কোন অ্যাপ্লিকেশন থার্ড-পার্টি সার্ভিসে থাকা আপনার ডেটা অ্যাক্সেস করতে পারবে এবং সেই ডেটার কোন কোন দিক তারা দেখতে বা পরিবর্তন করতে পারবে।

আপনার স্ক্রিপ্টে

রিমোট সার্ভারের সাথে অনুমোদন করুন । সার্ভার যে ধরনের অনুমোদন দিয়েছে, তার উপর নির্ভর করে একটি ভিন্ন ধাপগুচ্ছ, যা একটি ফ্লো (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

রিফ্রেশ টোকেন মঞ্জুর

রিফ্রেশ টোকেন প্রদান প্রক্রিয়াটি ক্লায়েন্ট ক্রেডেনশিয়াল প্রদানের অনুরূপ, এক্ষেত্রে সার্ভারে করা কোনো অনুরোধের ফলে একটি অ্যাক্সেস টোকেন ফেরত আসে যা সেশনে ব্যবহার করা যায়।

টোকেন রিফ্রেশ করুন

একটি রিফ্রেশ টোকেন সংগ্রহ করুন

রিফ্রেশ টোকেন প্রদানের ক্ষেত্রে পার্থক্যটি হলো এই যে, ক্লায়েন্ট ক্রেডেনশিয়াল প্রদানের জন্য প্রয়োজনীয় বিবরণ অ্যাপ্লিকেশন কনফিগারেশন থেকে আসে (উদাহরণস্বরূপ, পরিষেবার কন্ট্রোল প্যানেল থেকে), কিন্তু রিফ্রেশ টোকেনটি আরও জটিল একটি প্রক্রিয়ার অংশ হিসেবে প্রদান করা হয়, যেমন একটি অথরাইজেশন কোড প্রদান , যার জন্য ব্যবহারকারীর হস্তক্ষেপের প্রয়োজন হবে।

অনুমোদন কোড

OAuth প্লেগ্রাউন্ড ব্যবহার করে একটি রিফ্রেশ টোকেন পাওয়া

OAuth2 প্লেগ্রাউন্ড একটি ইউজার ইন্টারফেস প্রদান করে, যা ব্যবহারকারীকে রিফ্রেশ টোকেন পাওয়ার জন্য অথরাইজেশন কোড প্রদানের প্রক্রিয়াটি ধাপে ধাপে সম্পন্ন করার সুযোগ দেয়।

উপরের ডানদিকের সেটিংস বোতামটি আপনাকে OAuth ফ্লোতে ব্যবহার করার জন্য সমস্ত প্যারামিটার নির্ধারণ করতে দেয়, যার মধ্যে রয়েছে:

  • অনুমোদন এন্ডপয়েন্ট : অনুমোদন প্রক্রিয়ার সূচনা হিসেবে ব্যবহৃত হয়।
  • টোকেন এন্ডপয়েন্ট : রিফ্রেশ টোকেনের সাথে ব্যবহার করে অ্যাক্সেস টোকেন পাওয়া যায়।
  • ক্লায়েন্ট আইডি এবং সিক্রেট : অ্যাপ্লিকেশনটির জন্য প্রয়োজনীয় পরিচয়পত্র।

ওঅথ প্লেগ্রাউন্ড

রিফ্রেশ টোকেন ব্যবহার

প্রাথমিক অনুমোদন সম্পন্ন হয়ে গেলে, পরিষেবাগুলি একটি রিফ্রেশ টোকেন ইস্যু করতে পারে যা পরবর্তীতে ক্লায়েন্ট ক্রেডেনশিয়াল ফ্লো-এর মতোই ব্যবহার করা যেতে পারে: 

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

সার্চ অ্যাডস ৩৬০ এর উদাহরণ

সার্চ অ্যাডস ৩৬০ এমন একটি এপিআই-এর উদাহরণ যা রিফ্রেশ টোকেনের সাথে ব্যবহার করা যায়। এই নমুনায়, একটি স্ক্রিপ্ট একটি রিপোর্ট তৈরি করে এবং ফেরত পাঠায় । অন্যান্য যেসব কাজ করা যেতে পারে তার সম্পূর্ণ বিবরণের জন্য সার্চ অ্যাডস ৩৬০ এপিআই রেফারেন্স দেখুন।

স্ক্রিপ্ট তৈরি করুন
  1. এপিআই কনসোলে একটি নতুন প্রজেক্ট তৈরি করুন এবং সার্চ অ্যাডস ৩৬০ গাইডে দেওয়া পদ্ধতি অনুসরণ করে একটি ক্লায়েন্ট আইডি, ক্লায়েন্ট সিক্রেট ও রিফ্রেশ টোকেন সংগ্রহ করুন, সেই সাথে সার্চ অ্যাডস ৩৬০ এপিআই সক্রিয় করা নিশ্চিত করুন।
  2. নমুনা স্ক্রিপ্টটি গুগল অ্যাডস-এর একটি নতুন স্ক্রিপ্টে পেস্ট করুন।
  3. কোড তালিকার নিচে নমুনা OAuth2 লাইব্রেরিটি পেস্ট করুন।
  4. ক্লায়েন্ট আইডি, ক্লায়েন্ট সিক্রেট এবং রিফ্রেশ টোকেনের সঠিক মান অন্তর্ভুক্ত করার জন্য স্ক্রিপ্টটি সংশোধন করুন।

অ্যাপস স্ক্রিপ্ট এক্সিকিউশন এপিআই উদাহরণ

এই উদাহরণটি অ্যাপস স্ক্রিপ্ট এক্সিকিউশন এপিআই ব্যবহার করে অ্যাপস স্ক্রিপ্টে একটি ফাংশন কার্যকর করার পদ্ধতি প্রদর্শন করে। এর মাধ্যমে আপনি গুগল অ্যাডস স্ক্রিপ্ট থেকে অ্যাপস স্ক্রিপ্ট কল করতে পারবেন।

একটি অ্যাপস স্ক্রিপ্ট তৈরি করুন

একটি নতুন স্ক্রিপ্ট তৈরি করুন । নিচের নমুনাটি ড্রাইভ থেকে ১০টি ফাইলের তালিকা দেখাবে: 

function listFiles() {
  const limit = 10;
  const files = [];
  const fileIterator = DriveApp.getFiles();
  while (fileIterator.hasNext() && limit) {
    files.push(fileIterator.next().getName());
    limit--;
  }
  return files;
}
কার্যকর করার জন্য অ্যাপস স্ক্রিপ্ট কনফিগার করুন
  1. স্ক্রিপ্টটি সংরক্ষণ করুন।
  2. রিসোর্স > ক্লাউড প্ল্যাটফর্ম প্রজেক্ট-এ ক্লিক করুন।
  3. এপিআই কনসোলে যেতে প্রজেক্টের নামে ক্লিক করুন।
  4. এপিআই এবং পরিষেবাগুলিতে যান।
  5. প্রাসঙ্গিক API-গুলো সক্রিয় করুন, এক্ষেত্রে Drive API এবং Apps Script Execution API ।
  6. মেনুতে থাকা ক্রেডেনশিয়ালস আইটেম থেকে OAuth ক্রেডেনশিয়াল তৈরি করুন।
  7. আপনার স্ক্রিপ্টে ফিরে এসে, Publish > Deploy as API Executable থেকে স্ক্রিপ্টটি কার্যকর করার জন্য প্রকাশ করুন।
গুগল অ্যাডস স্ক্রিপ্ট তৈরি করুন
  1. নমুনা স্ক্রিপ্টটি গুগল অ্যাডস-এর একটি নতুন স্ক্রিপ্টে পেস্ট করুন।
  2. এছাড়াও, কোড তালিকার নিচে নমুনা OAuth2 লাইব্রেরিটি পেস্ট করুন।
  3. ক্লায়েন্ট আইডি, ক্লায়েন্ট সিক্রেট এবং রিফ্রেশ টোকেনের সঠিক মান অন্তর্ভুক্ত করার জন্য স্ক্রিপ্টটি সংশোধন করুন।

পরিষেবা অ্যাকাউন্ট

অনুদান প্রকারের একটি বিকল্প হলো পরিষেবা অ্যাকাউন্টের ধারণা।

সার্ভিস অ্যাকাউন্ট এবং গ্রান্ট টাইপের মধ্যে পার্থক্য হলো, এগুলো ব্যবহারকারীর ডেটা অ্যাক্সেস করার জন্য ব্যবহৃত হয় না। অথেনটিকেশনের পর, প্রজেক্টের মালিক ব্যবহারকারীর পক্ষ থেকে নয়, বরং অ্যাপ্লিকেশনটির পক্ষ থেকে সার্ভিস অ্যাকাউন্টই অনুরোধগুলো করে থাকে। উদাহরণস্বরূপ, যদি সার্ভিস অ্যাকাউন্টটি ড্রাইভ এপিআই (Drive API) ব্যবহার করে একটি ফাইল তৈরি করে, তবে সেই ফাইলটি সার্ভিস অ্যাকাউন্টের অধীনে আসবে এবং ডিফল্টভাবে প্রজেক্টের মালিকের কাছে তা অ্যাক্সেসযোগ্য হবে না।

গুগল প্রাকৃতিক ভাষা এপিআই উদাহরণ

ন্যাচারাল ল্যাঙ্গুয়েজ এপিআই টেক্সটের জন্য সেন্টিমেন্ট অ্যানালাইসিস এবং এনটিটি অ্যানালাইসিস প্রদান করে।

এই উদাহরণটি বিজ্ঞাপনের টেক্সটের—যার মধ্যে হেডলাইন বা ডেসক্রিপশনও অন্তর্ভুক্ত— সেন্টিমেন্ট গণনা করার পদ্ধতি ব্যাখ্যা করে। এর মাধ্যমে বার্তাটি কতটা ইতিবাচক এবং এর গুরুত্ব কতটা, তা পরিমাপ করা যায়: কোনটি ভালো, ‘ আমরা কেক বিক্রি করি ’ নাকি ‘আমরা লন্ডনের সেরা কেক বিক্রি করি। আজই কিনুন! ’?

স্ক্রিপ্টটি সেট আপ করুন
  1. এপিআই কনসোলে একটি নতুন প্রজেক্ট তৈরি করুন
  2. ন্যাচারাল ল্যাঙ্গুয়েজ এপিআই সক্রিয় করুন
  3. প্রকল্পটির জন্য বিলিং চালু করুন।
  4. একটি সার্ভিস অ্যাকাউন্ট তৈরি করুন । ক্রেডেনশিয়াল JSON ফাইলটি ডাউনলোড করুন।
  5. নমুনা স্ক্রিপ্টটি গুগল অ্যাডস-এর একটি নতুন স্ক্রিপ্টে পেস্ট করুন।
  6. এছাড়াও, কোড তালিকার নিচে নমুনা OAuth2 লাইব্রেরিটি পেস্ট করুন।
  7. প্রয়োজনীয় মানগুলি প্রতিস্থাপন করুন:
    • serviceAccount : সার্ভিস অ্যাকাউন্টের ইমেল ঠিকানা, উদাহরণস্বরূপ xxxxx@yyyy.iam.gserviceaccount.com ।
    • key : সার্ভিস অ্যাকাউন্ট তৈরি করার সময় ডাউনলোড করা JSON ফাইলের কী। শুরু হয় -----BEGIN PRIVATE KEY... এবং শেষ হয় ...END PRIVATE KEY-----\n ।

এপিআই প্রতিক্রিয়া

এপিআই বিভিন্ন ফরম্যাটে ডেটা ফেরত দিতে পারে। এগুলোর মধ্যে সবচেয়ে উল্লেখযোগ্য হলো এক্সএমএল (XML) এবং জেএসওএন (JSON)।

JSON

রেসপন্স ফরম্যাট হিসেবে XML-এর চেয়ে JSON নিয়ে কাজ করা সাধারণত সহজ। তবে, এখনও কিছু সমস্যা দেখা দিতে পারে।

প্রতিক্রিয়া যাচাইকরণ

এপিআই-তে কল করে সফল প্রতিক্রিয়া পাওয়ার পর, পরবর্তী সাধারণ পদক্ষেপটি হলো JSON.parse ব্যবহার করে JSON স্ট্রিংটিকে একটি জাভাস্ক্রিপ্ট অবজেক্টে রূপান্তর করা। এই পর্যায়ে, পার্সিং ব্যর্থ হলে তার সমাধান করা যুক্তিযুক্ত: 

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
}

এক্সএমএল

বৈধতা

এপিআই তৈরির জন্য এক্সএমএল এখনও একটি জনপ্রিয় ফরম্যাট। এপিআই কলের প্রতিক্রিয়া XmlService-এর parse মেথড ব্যবহার করে পার্স করা যায়: 

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

যদিও XmlService.parse এক্সএমএল-এর ত্রুটি শনাক্ত করে এবং সেই অনুযায়ী এক্সেপশন থ্রো করে, এটি কোনো স্কিমার সাপেক্ষে এক্সএমএল-কে ভ্যালিডেট করার সুবিধা দেয় না।

মূল উপাদান

XML ডকুমেন্টটি সফলভাবে পার্স করা হলে, getRootElement() মেথড ব্যবহার করে রুট এলিমেন্টটি পাওয়া যায়: 

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

নেমস্পেস

নিম্নলিখিত উদাহরণে, নির্বাচিত ম্যাচগুলির ফুটবল ফলাফল পেতে স্পোর্টরাডার এপিআই ব্যবহার করা হয়েছে। এক্সএমএল প্রতিক্রিয়াটি নিম্নলিখিত বিন্যাস গ্রহণ করে: 

<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() ব্যবহার করে প্রতিটি চাইল্ডের ওপর পুনরাবৃত্তি করার কথা বিবেচনা করুন।

স্পোর্টরাডার উদাহরণ

এই সম্পূর্ণ স্পোর্টরাডার উদাহরণটি ফুটবল ম্যাচের, বিশেষ করে ইংলিশ প্রিমিয়ার লিগের ম্যাচের বিবরণ পুনরুদ্ধার করার পদ্ধতি তুলে ধরে। সকার এপিআই হলো স্পোর্টরাডারের দেওয়া বিভিন্ন স্পোর্টস ফিডের মধ্যে একটি।

একটি স্পোর্টরাডার অ্যাকাউন্ট তৈরি করুন
  1. স্পোর্টরাডার ডেভেলপার সাইটে যান
  2. একটি ট্রায়াল অ্যাকাউন্টের জন্য নিবন্ধন করুন।
  3. নিবন্ধন করার পর, আপনার অ্যাকাউন্টে সাইন ইন করুন।
  4. লগ ইন করার পর, MyAccount- এ যান।

স্পোর্টরাডার বিভিন্ন খেলাধুলাকে আলাদা আলাদা এপিআই-তে বিভক্ত করে। উদাহরণস্বরূপ, আপনি সকার এপিআই-এর অ্যাক্সেস কিনতে পারেন কিন্তু টেনিস এপিআই-এর নয়। আপনার তৈরি করা প্রতিটি অ্যাপ্লিকেশনের সাথে বিভিন্ন খেলাধুলা এবং ভিন্ন ভিন্ন কী যুক্ত থাকতে পারে।

  1. অ্যাপ্লিকেশন-এর অধীনে ‘ একটি নতুন অ্যাপ্লিকেশন তৈরি করুন’-এ ক্লিক করুন। অ্যাপ্লিকেশনটির একটি নাম ও বিবরণ দিন এবং ওয়েবসাইট ক্ষেত্রটি উপেক্ষা করুন।
  2. শুধুমাত্র Soccer Trial Europe v2-এর জন্য একটি নতুন কী ইস্যু করার বিকল্পটি নির্বাচন করুন।
  3. আবেদন নিবন্ধন করতে ক্লিক করুন।

সফল হলে, এর ফলে এমন একটি পৃষ্ঠা আসবে যেখানে আপনার নতুন এপিআই কী-টি থাকবে।

  1. নমুনা স্ক্রিপ্টটি গুগল অ্যাডস-এর একটি নতুন স্ক্রিপ্টে পেস্ট করুন।
  2. তালিকায় থাকা API কী-টি নতুন ইস্যু করা কী-টি দিয়ে প্রতিস্থাপন করুন এবং ইমেল ঠিকানার ফিল্ডটি সম্পাদনা করুন।

সমস্যা সমাধান

থার্ড-পার্টি এপিআই নিয়ে কাজ করার সময় বিভিন্ন কারণে ত্রুটি ঘটতে পারে, যেমন:

  • ক্লায়েন্টরা এপিআই-এর প্রত্যাশিত নয় এমন ফরম্যাটে সার্ভারে অনুরোধ পাঠাচ্ছে।
  • যেসব ক্লায়েন্ট প্রাপ্ত প্রতিক্রিয়ার ধরন থেকে ভিন্ন ধরনের প্রতিক্রিয়া আশা করছেন।
  • ক্লায়েন্টরা অবৈধ টোকেন বা কী ব্যবহার করছে, অথবা মানগুলোকে প্লেসহোল্ডার হিসেবে রেখে দিয়েছে।
  • ক্লায়েন্টরা ব্যবহারের সীমায় পৌঁছে যাচ্ছে।
  • ক্লায়েন্টরা অবৈধ প্যারামিটার সরবরাহ করছে।

এই সমস্ত ক্ষেত্রে এবং অন্যান্য ক্ষেত্রেও, সমস্যার কারণ শনাক্ত করার একটি ভালো প্রথম পদক্ষেপ হলো ত্রুটি সৃষ্টিকারী প্রতিক্রিয়াটির বিস্তারিত পরীক্ষা করা।

প্রতিক্রিয়াগুলি বিশ্লেষণ করুন

ডিফল্টরূপে, যে কোনো প্রতিক্রিয়া যা একটি ত্রুটি ফেরত দেয় ( স্ট্যাটাস কোড 400 বা তার বেশি), তা গুগল অ্যাডস স্ক্রিপ্ট ইঞ্জিন দ্বারা থ্রো করা হবে।

এই আচরণটি প্রতিরোধ করতে, এবং ত্রুটি ও ত্রুটির বার্তা পর্যালোচনার সুযোগ দিতে, ঐচ্ছিক প্যারামিটারগুলোর muteHttpExceptions প্রপার্টিটি UrlFetchApp.fetch এ সেট করুন। উদাহরণস্বরূপ: 

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

সাধারণ স্ট্যাটাস কোড

  • 200 OK সফলতা নির্দেশ করে। যদি প্রতিক্রিয়ায় প্রত্যাশিত ডেটা না থাকে, তবে বিবেচনা করুন যে:

    • কিছু এপিআই-তে কোন ফিল্ড এবং/অথবা রেসপন্স ফরম্যাট ব্যবহার করা হবে তা নির্দিষ্ট করে দেওয়ার সুযোগ থাকে। এ বিষয়ে বিস্তারিত জানতে এপিআই ডকুমেন্টেশন দেখুন।
    • একটি API-তে একাধিক রিসোর্স থাকতে পারে যা কল করা যায়। অন্য কোনো রিসোর্স ব্যবহার করা বেশি উপযুক্ত হবে কিনা এবং সেটি আপনার প্রয়োজনীয় ডেটা ফেরত দেবে কিনা, তা নির্ধারণ করতে ডকুমেন্টেশন দেখুন।
    • কোডটি লেখার পর থেকে এপিআই (API) পরিবর্তিত হয়ে থাকতে পারে। বিষয়টি পরিষ্কারভাবে জানতে ডকুমেন্টেশন অথবা ডেভেলপারের সাথে যোগাযোগ করুন।

  • 400 Bad Request সাধারণ অর্থ হলো, সার্ভারে পাঠানো রিকোয়েস্টের ফরম্যাটিং বা কাঠামোতে কোনো সমস্যা আছে। রিকোয়েস্টটি পরীক্ষা করুন এবং এটি প্রত্যাশা অনুযায়ী আছে কিনা তা নিশ্চিত করতে এপিআই স্পেসিফিকেশনের সাথে তুলনা করুন। কীভাবে রিকোয়েস্টগুলো পরীক্ষা করতে হয়, সে সম্পর্কে বিস্তারিত জানতে ‘ইনসপেক্ট রিকোয়েস্টস’ দেখুন।

  • 401 Unauthorized মানে সাধারণত এই যে, অনুমোদন প্রদান না করে বা সফলভাবে অনুমোদন সম্পন্ন না করেই এপিআই-কে কল করা হচ্ছে।

    • যদি এপিআইটি বেসিক অথরাইজেশন ব্যবহার করে, তাহলে নিশ্চিত করুন যে রিকোয়েস্টে Authorization হেডারটি তৈরি ও সরবরাহ করা হচ্ছে।
    • যদি API-টি OAuth 2.0 ব্যবহার করে, তাহলে নিশ্চিত করুন যে অ্যাক্সেস টোকেনটি সংগ্রহ করা হয়েছে এবং এটি একটি Bearer টোকেন হিসেবে সরবরাহ করা হচ্ছে।
    • অনুমোদনের অন্য কোনো ভিন্নতার ক্ষেত্রে, অনুরোধের জন্য প্রয়োজনীয় পরিচয়পত্র সরবরাহ করা হচ্ছে কিনা তা নিশ্চিত করুন।

  • 403 Forbidden নির্দেশ করে যে, অনুরোধ করা রিসোর্সটির জন্য ব্যবহারকারীর অনুমতি নেই।

    • নিশ্চিত করুন যে ব্যবহারকারীকে প্রয়োজনীয় অনুমতি দেওয়া হয়েছে, যেমন, ফাইল-ভিত্তিক অনুরোধের ক্ষেত্রে ব্যবহারকারীকে কোনো ফাইলে প্রবেশাধিকার দেওয়া।

  • 404 Not Found অর্থ হলো অনুরোধকৃত রিসোর্সটির অস্তিত্ব নেই।

    • এপিআই এন্ডপয়েন্টের জন্য ব্যবহৃত ইউআরএলটি সঠিক কিনা তা যাচাই করুন।
    • কোনো রিসোর্স ফেচ করার সময়, রেফারেন্স করা রিসোর্সটির অস্তিত্ব আছে কিনা তা যাচাই করুন (উদাহরণস্বরূপ, ফাইল-ভিত্তিক API-এর ক্ষেত্রে ফাইলটি বিদ্যমান আছে কিনা)।

অনুরোধগুলি পরিদর্শন করুন

যখন এপিআই (API) প্রতিক্রিয়া থেকে বোঝা যায় যে অনুরোধটি ত্রুটিপূর্ণ, যেমন একটি 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() -এর সরাসরি প্রতিস্থাপন হিসেবে ব্যবহার করা যেতে পারে।

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

আপনার স্ক্রিপ্টটি চালানোর সময়, সমস্ত অনুরোধ এবং প্রতিক্রিয়ার বিবরণ কনসোলে লগ করা হয়, যা ডিবাগিং সহজ করে তোলে।