میاناهای برنامه‌سازی کاربردی شخص ثالث

یکی از ویژگی‌های قدرتمند جاوااسکریپت Google Ads، توانایی ادغام با داده‌ها و سرویس‌های میاناهای برنامه‌سازی کاربردی طرف سوم است.

این راهنما مفاهیم زیر را پوشش می‌دهد که می‌تواند به شما در نوشتن اسکریپت‌ها برای اتصال به سرویس‌های دیگر کمک کند:

  • ایجاد درخواست‌های HTTP: نحوه استفاده از UrlFetchApp برای دسترسی به میاناهای برنامه‌سازی کاربردی خارجی.
  • اصالت‌سنجی: برخی‌از سناریوهای رایج اصالت‌سنجی را پوشش می‌دهیم.
  • تجزیه پاسخ‌ها: نحوه پردازش داده‌های JSON و XML برگردانده‌شده.

همچنین نمونه‌هایی برای تعدادی از میاناهای برنامه‌سازی کاربردی محبوب ارائه کرده‌ایم که این مفاهیم را نشان می‌دهند.

واکشی داده‌ها با UrlFetchApp

UrlFetchApp عملکرد اصلی موردنیاز برای تعامل با میاناهای برنامه‌سازی کاربردی طرف سوم را ارائه می‌دهد.

مثال زیر واکشی داده‌های آب‌وهوا را از OpenWeatherMap نشان می‌دهد. ما OpenWeatherMap را به‌دلیل طرح مجوزدهی و API نسبتاً ساده آن انتخاب کردیم.

درخواست دادن

مستندات 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 ارائه می‌دهند. این نشان‌دهنده سری‌سازی اشیای جاوا اسکریپت است، به‌طوری‌که اشیا، آرایه‌ها، و انواع پایه را می‌توان به‌صورت رشته نشان داد و منتقل کرد.

برای تبدیل رشته JSON (مثل رشته‌ای که از OpenWeatherMap برگردانده شده است) به شیء جاوا اسکریپت، از روش توکار JSON.parse استفاده کنید. ادامه مثال قبلی:

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

روش JSON.parse رشته را به شیء تبدیل می‌کند که دارای ویژگی name است.

برای جزئیات بیشتر درباره کار با پاسخ‌های میانای برنامه‌سازی کاربردی در قالب‌های مختلف، بخش تجزیه پاسخ‌ها را ببینید.

مدیریت کردن خطا

رسیدگی به خطا نکته مهمی است که باید هنگام کار با میاناهای برنامه‌سازی کاربردی طرف سوم در دستوراتتان درنظر بگیرید، زیرا میاناهای برنامه‌سازی کاربردی طرف سوم اغلب به‌طور مکرر تغییر می‌کنند و مقادیر پاسخ غیرمنتظره‌ای تولید می‌کنند، برای مثال:

  • نشانی وب یا پارامترهای میانای برنامه‌سازی کاربردی ممکن است بدون اطلاع شما تغییر کند.
  • کلید میانای برنامه‌سازی کاربردی (یا دیگر اعتبارنامه کاربر) شما ممکن است منقضی شود.
  • قالب پاسخ ممکن است بدون اطلاع قبلی تغییر کند.

رمزهای وضعیت اچ‌تی‌تی‌پی‌اس

به‌دلیل احتمال پاسخ‌های غیرمنتظره، باید رمز وضعیت HTTP را بررسی کنید. به‌طور پیش‌فرض، UrlFetchApp درصورت مواجه شدن با کد خطای HTTP، استثنایی را ایجاد می‌کند. برای تغییر این رفتار، لازم است پارامتر اختیاری را ارسال کنید، مانند مثال زیر:

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

داده‌های POST با UrlFetchApp

نمونه مقدماتی با OpenWeatherMap فقط داده‌ها را واکشی کرد. معمولاً فراخوانی‌های API که وضعیت را در سرور راه دور تغییر نمی‌دهند از روش HTTP GET استفاده می‌کنند.

روش GET روش پیش‌فرض برای UrlFetchApp است. بااین‌حال، برخی‌از فراخوانی‌های API، مانند فراخوانی‌های سرویسی که پیامک ارسال می‌کند، به روش‌های دیگری مانند POST یا PUT نیاز دارند.

برای نشان دادن نحوه استفاده از فراخوانی‌های POST با UrlFetchApp، مثال زیر ادغام با Slack، برنامه پیام‌رسانی مشارکتی، را برای ارسال پیام Slack به کاربران و گروه‌های Slack نشان می‌دهد.

راه‌اندازی Slack

این راهنما فرض می‌کند که قبلاً برای حساب Slack ثبت‌نام کرده‌اید.

همانند OpenWeatherMap در مثال قبلی، برای فعال کردن ارسال پیام، دریافت کردن یک توکن ضروری است. Slack نشانی وب یکتایی ارائه می‌دهد که به شما امکان می‌دهد به تیمتان پیام ارسال کنید، به این نشانی وب وب‌هوک ورودی می‌گویند.

با کلیک کردن روی افزودن ادغام وب‌قلاب‌های ورودی و دنبال کردن دستورالعمل‌ها، وب‌قلاب ورودی را راه‌اندازی کنید. این فرایند باید نشانی وبی را برای استفاده در پیام‌رسانی صادر کند.

ایجاد درخواست پست

پس‌از راه‌اندازی «وب‌قلاب ورودی»، برای ایجاد درخواست POST باید از برخی ویژگی‌های اضافی در پارامتر options که به UrlFetchApp.fetch ارسال شده است استفاده کنید:

  • 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 مراجعه کنید.

اطلاعات فرم

نمونه قبلی استفاده از رشته JSON را به‌عنوان ویژگی payload برای درخواست 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 تنظیم شده است.

برخی‌از میاناهای برنامه‌سازی کاربردی هنگام ارسال درخواست‌های POST به استفاده از داده‌های فرم نیاز دارند، بنابراین خوب است که این تبدیل خودکار از اشیاء جاوا اسکریپت به داده‌های فرم را به‌خاطر داشته باشید.

اصالت‌سنجی پایه HTTP

اصالت‌سنجی پایه HTTP یکی از ساده‌ترین شکل‌های اصالت‌سنجی است و توسط بسیاری از میاناهای برنامه‌سازی کاربردی (API) استفاده می‌شود.

اصالت‌سنجی با پیوست کردن نام کاربری و گذرواژه کدگذاری‌شده به سرایندهای HTTP در هر درخواست انجام می‌شود.

اصالت‌سنجی پایه HTTP

ساختن درخواست

مراحل زیر برای تولید درخواست اصالت‌سنجی‌شده لازم است:

  1. عبارت عبور را با پیوستن نام کاربری و گذرواژه با دونقطه تشکیل دهید، برای مثال username:password.
  2. گذرعبارت را براساس Base64 کدبندی کنید، برای مثال username:password به dXNlcm5hbWU6cGFzc3dvcmQ= تبدیل می‌شود.
  3. سرصفحه 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);

نمونه‌های اصالت‌سنجی پایه

بخش نمونه‌های کد شامل دو نمونه است که استفاده از «اصالت‌سنجی پایه HTTP» را نشان می‌دهد:

Plivo

Plivo سرویسی است که ارسال و دریافت پیامک را با میانای برنامه‌سازی کاربردی خود تسهیل می‌کند. این نمونه ارسال پیام را نشان می‌دهد.

  1. در Plivo ثبت‌نام کنید.
  2. نمونه متن را در متن جدیدی در Google Ads جای‌گذاری کنید.
  3. مقادیر PLIVO_ACCOUNT_AUTHID و PLIVO_ACCOUNT_AUTHTOKEN را با مقادیر موجود در داشبورد مدیریت جایگزین کنید.
  4. نشانی ایمیلتان را همان‌طور که در اسکریپت برای اعلان خطاها مشخص شده است وارد کنید.
  5. برای استفاده از Plivo، باید شماره خریداری کنید یا شماره‌هایی را به حساب آزمایشی اضافه کنید. شماره‌های Sandbox را اضافه کنید که می‌توانند با حساب آزمایشی استفاده شوند.
  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 در انواع و نسخه‌های مختلفی ارائه می‌شود.

درحالی‌که با اصالت‌سنجی پایه HTTP، کاربر فقط یک نام کاربری و گذرواژه دارد، OAuth به برنامه‌های شخص ثالث اجازه می‌دهد بااستفاده از اطلاعات اعتباری مختص آن برنامه شخص ثالث، به حساب و داده‌های کاربر دسترسی پیدا کنند. علاوه‌براین، میزان دسترسی نیز مختص آن برنامه خواهد بود.

برای اطلاعات بیشتر درباره OAuth 1.0، به راهنمای OAuth Core مراجعه کنید. به‌ویژه، 6 را ببینید. درحال اصالت‌سنجی با OAuth. در OAuth 1.0 کامل سه-پایه، فرایند به‌صورت زیر است:

  1. برنامه («مصرف‌کننده») یک کد درخواست دریافت می‌کند.
  2. کاربر توکن درخواست را مجاز می‌کند.
  3. برنامه کد درخواست را با کد دسترسی مبادله می‌کند.
  4. برای همه درخواست‌های منبع بعدی، از کد دسترسی در درخواست امضاشده استفاده می‌شود.

برای سرویس‌های طرف سوم برای استفاده از OAuth 1.0 بدون تعامل کاربر (برای مثال همان‌طور که جاوااسکریپت Google Ads نیاز دارد) مراحل ۱، ۲، و ۳ امکان‌پذیر نیست. بنابراین، برخی‌از سرویس‌ها کد دسترسی را از کنسول پیکربندی‌شان صادر می‌کنند و به برنامه اجازه می‌دهند مستقیماً به مرحله ۴ برود. این حالت به‌عنوان OAuth 1.0 یک‌طرفه شناخته می‌شود.

OAuth1

OAuth 1.0 در جاوااسکریپت Google Ads

برای اسکریپت‌های Google Ads، هر اسکریپت معمولاً به‌عنوان یک برنامه تفسیر می‌شود. ازطریق کنسول یا صفحه تنظیمات مدیریت برای سرویس، معمولاً لازم است:

  • پیکربندی برنامه را برای نمایش دادن این اسکریپت راه‌اندازی کنید.
  • مشخص کنید چه اجازه‌هایی به دستورگان داده می‌شود.
  • کلید مصرف‌کننده، رمز مصرف‌کننده، کد دسترسی، و رمز دسترسی را برای استفاده با OAuth یک‌طرفه دریافت کنید.

OAuth 2.0

OAuth 2.0 در میاناهای برنامه‌سازی کاربردی محبوب برای ارائه دسترسی به داده‌های کاربر استفاده می‌شود. مالک حساب برای سرویس طرف سوم مشخصی به برنامه‌های خاصی اجازه می‌دهد تا به داده‌های کاربر دسترسی داشته باشند. مزایای آن این است که مالک:

  • لازم نیست اعتبارنامه‌های حسابش را با برنامه هم‌رسانی کند.
  • می‌تواند کنترل کند کدام برنامه‌ها به‌طور جداگانه به داده‌ها دسترسی داشته باشند و تا چه حد. (برای مثال، دسترسی اعطاشده ممکن است فقط خواندنی باشد، یا فقط به زیرمجموعه‌ای از داده‌ها باشد.)

برای استفاده از سرویس‌های فعال‌شده با OAuth 2.0 در اسکریپت‌های Google Ads، چند مرحله وجود دارد:

خارج از متن شما

به جاوااسکریپت 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 playground میانای کاربری ارائه می‌دهد که به کاربر اجازه می‌دهد با گذراندن مراحل اعطای کد مجوز، ژتون بازآوری دریافت کند.

دکمه تنظیمات در بالا سمت چپ به شما امکان می‌دهد همه پارامترهای مورد استفاده در جریان OAuth را تعریف کنید، ازجمله:

  • نقطه پایانی مجوز: به‌عنوان شروع جریان برای مجوز استفاده می‌شود.
  • نقطه پایانی کد: با کد بازآوری برای دریافت کد دسترسی استفاده می‌شود.
  • شناسه و رمز کارخواه: اطلاعات اعتباری برای برنامه.

    OAuth Playground

بازآوری مصرف داده‌واحد

پس‌از انجام مجوزدهی اولیه، سرویس‌ها می‌توانند ژتون بازآوری صادر کنند که سپس می‌توان از آن به روشی مشابه با جریان اطلاعات کاربری کارخواه استفاده کرد:

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 مراجعه کنید.

ایجاد کردن متن
  1. پروژه جدیدی در کنسول Google Cloud ایجاد کنید و با دنبال کردن روال موجود در راهنمای Search Ads 360، شناسه کارخواه، رمز کارخواه، و ژتون بازآوری را دریافت کنید و مطمئن شوید که Search Ads 360 API را فعال کرده‌اید.
  2. [نمونه اسکریپت][search-ads-360-example] را در اسکریپت جدیدی در Google Ads جای‌گذاری کنید.
  3. [نمونه کتابخانه OAuth2][oauth20-library-example] را در زیر فهرست کد جای‌گذاری کنید.
  4. دستورگان را اصلاح کنید تا حاوی مقادیر صحیح برای شناسه کارخواه، رمز کارخواه، و ژتون بازآوری باشد.

نمونه API اجرای اسکریپت Apps

این مثال اجرای تابعی را در Apps Script بااستفاده از Apps Script Execution API نشان می‌دهد. این به شما امکان می‌دهد Apps Script را از جاوااسکریپت Google Ads فراخوانی کنید.

ایجاد کردن اسکریپت Apps Script

ایجاد کردن دستورات جدید. نمونه زیر ۱۰ فایل را از Drive فهرست می‌کند:

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. روی نام پروژه کلیک کنید تا به کنسول Google Cloud بروید.
  4. به میاناهای برنامه‌سازی کاربردی و سرویس‌ها بروید.
  5. میاناهای برنامه‌سازی کاربردی مناسب را فعال کنید، در این مورد Drive API و Apps Script Execution API.
  6. اعتبارنامه‌های OAuth را از گزینه اعتبارنامه‌ها در منو ایجاد کنید.
  7. به اسکریپت خود برگردید، اسکریپت را برای اجرا از انتشار > استقرار به‌عنوان API قابل‌اجرا منتشر کنید.
ایجاد جاوااسکریپت Google Ads
  1. نمونه متن را در متن جدیدی در Google Ads جای‌گذاری کنید.
  2. علاوه‌براین، [نمونه کتابخانه OAuth2][oauth20-library-example] را زیر فهرست کد جای‌گذاری کنید.
  3. دستورگان را اصلاح کنید تا حاوی مقادیر صحیح برای شناسه کارخواه، رمز کارخواه، و ژتون بازآوری باشد.

حساب‌های سرویس

جایگزین انواع اعطای مجوز، مفهوم حساب‌های سرویس است.

حساب‌های خدمات با انواع اعطای مجوز تفاوت دارند زیرا از آن‌ها برای دسترسی به داده‌های کاربر استفاده نمی‌شود: پس‌از اصالت‌سنجی، درخواست‌ها توسط «حساب خدمات» ازطرف برنامه انجام می‌شود، نه به‌عنوان کاربری که ممکن است مالک پروژه باشد. برای مثال، اگر حساب سرویس از Drive API برای ایجاد فایل استفاده کند، این فایل به حساب سرویس تعلق خواهد داشت و به‌طور پیش‌فرض برای مالک پروژه دردسترس نخواهد بود.

نمونه Google natural language API

[میانای برنامه‌سازی کاربردی زبان طبیعی][natural-language-api-docs] [تحلیل احساسات][sentiment-analysis-api-docs] و [تحلیل موجودیت][entity-analysis-api-docs] را برای نوشتار ارائه می‌دهد.

این مثال نحوه محاسبه [احساسات][sentiment-api-docs] را برای نوشتار آگهی (ازجمله عنوان یا شرح) نشان می‌دهد. این کار معیاری برای میزان مثبت بودن پیام و اهمیت آن ارائه می‌دهد: کدام‌یک بهتر است، ما کیک می‌فروشیم یا ما بهترین کیک‌ها را در لندن می‌فروشیم. همین امروز بخرید!؟

راه‌اندازی دستورگان
  1. پروژه جدیدی در کنسول Google Cloud ایجاد کنید.
  2. [Natural Language API][natural-language-api] را فعال کنید.
  3. صدور صورت‌حساب را برای پروژه فعال کنید.
  4. [ایجاد حساب سرویس][create-service-account]. فایل JSON اطلاعات کاربری را بارگیری کنید.
  5. [نمونه جاوااسکریپت][natural-language-example] را در جاوااسکریپت جدیدی در Google Ads جای‌گذاری کنید.
  6. علاوه‌براین، [نمونه کتابخانه OAuth2][oauth20-library-example] را زیر فهرست کد جای‌گذاری کنید.
  7. مقادیر لازم را جایگزین کنید:
    • serviceAccount: نشانی ایمیل «حساب سرویس»، برای مثال xxxxx@yyyy.iam.gserviceaccount.com.
    • key: کلید فایل JSON بارگیری‌شده هنگام ایجاد «حساب سرویس». -----BEGIN PRIVATE KEY... شروع می‌شود و ...END PRIVATE KEY-----\n پایان می‌یابد.

پاسخ‌های میانای برنامه‌سازی کاربردی

میاناهای برنامه‌سازی کاربردی می‌توانند داده‌ها را در قالب‌های مختلفی برگردانند. مهم‌ترین آن‌ها XML و JSON هستند.

(قالب) JSON

JSON معمولاً ساده‌تر از XML است تا به‌عنوان قالب پاسخ با آن کار کنید. بااین‌حال، هنوز مشکلاتی وجود دارد که ممکن است پیش بیاید.

اعتبارسنجی پاسخ

پس‌از دریافت پاسخ موفقیت‌آمیز از فراخوانی میانای برنامه‌سازی کاربردی، مرحله بعدی معمولاً استفاده از JSON.parse برای تبدیل رشته JSON به شیء جاوا اسکریپت است. در این مرحله، منطقی است که موردی را که تجزیه ناموفق است مدیریت کنید:

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

همچنین، اگر API تحت کنترل شما نیست، درنظر داشته باشید که ساختار پاسخ ممکن است تغییر کند و ویژگی‌ها ممکن است دیگر وجود نداشته باشند:

// 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 به دستورات شما اجازه می‌دهد داده‌ها را از بدنه پاسخ XML تجزیه و استخراج کنند.

اعتبارسنجی

XML هنوز هم قالبی محبوب برای ساختن میاناهای برنامه‌سازی کاربردی است. پاسخ فراخوانی API را می‌توان بااستفاده از روش XmlService parse تجزیه کرد:

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

درحالی‌که XmlService.parse خطاها را در XML شناسایی می‌کند و استثناهایی را مطابق با آن ایجاد می‌کند، امکان اعتبارسنجی XML دربرابر طرح‌واره را فراهم نمی‌کند.

عنصر ریشه

با فرض تجزیه موفقیت‌آمیز سند XML، عنصر ریشه بااستفاده از روش getRootElement() به‌دست می‌آید:

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

فضاهای نام

در مثال زیر، از Sportradar API برای دریافت نتایج فوتبال برای مسابقات انتخاب‌شده استفاده می‌شود. پاسخ XML قالب زیر را دارد:

<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
  1. به سایت توسعه‌دهنده Sportradar بروید
  2. برای حساب آزمایشی ثبت‌نام کنید.
  3. پس‌از ثبت‌نام، به سیستم حسابتان وارد شوید.
  4. پس‌از ورود به سیستم، به حساب من بروید.

‫Sportradar ورزش‌های مختلف را به میاناهای برنامه‌سازی کاربردی مختلف تقسیم می‌کند. برای مثال، ممکن است دسترسی به Soccer API را خریداری کنید اما Tennis API را خریداری نکنید. هر «برنامه‌ای» که ایجاد می‌کنید می‌تواند ورزش‌های مختلفی را به خود اختصاص دهد و کلیدهای متفاوتی داشته باشد.

  1. در بخش «برنامه‌ها»، روی ایجاد برنامه جدید کلیک کنید. نام و شرحی برای برنامه وارد کنید و فیلد وب‌سایت را نادیده بگیرید.
  2. فقط صدور کلید جدید برای Soccer Trial Europe v2 را انتخاب کنید.
  3. روی ثبت برنامه کلیک کنید.

پس‌از موفقیت، این کار باید به صفحه‌ای با کلید میانای API جدید شما منجر شود.

  1. نمونه اسکریپت را در اسکریپت جدیدی در Google Ads جای‌گذاری کنید.
  2. کلید میانای API را در فهرستگان با کلید جدیداً صادرشده جایگزین کنید و فیلد نشانی ایمیل را ویرایش کنید.

عیب‌یابی

هنگام کار با میاناهای برنامه‌سازی کاربردی طرف سوم، ممکن است به دلایل مختلفی خطا رخ دهد، برای مثال:

  • کارخواه‌هایی که درخواست‌ها را در قالبی که برای API غیرمنتظره است به سرور ارسال می‌کنند.
  • مشتریانی که انتظار قالب پاسخی متفاوت از آنچه با آن مواجه شده‌اند را دارند.
  • مشتریانی که از کلیدها یا کدهای نامعتبر استفاده می‌کنند، یا مقادیری که به‌عنوان جای‌بان باقی مانده‌اند.
  • مشتریان به حد استفاده رسیده‌اند.
  • کارخواه‌ها پارامترهای نامعتبر ارائه می‌دهند.

در همه این موارد و موارد دیگر، اولین گام خوب برای شناسایی علت مشکل، بررسی جزئیات پاسخی است که باعث خطا شده است.

تجزیه پاسخ‌ها

به‌طور پیش‌فرض، هر پاسخی که خطایی را برمی‌گرداند (کد وضعیت ۴۰۰ یا بالاتر) توسط موتور اسکریپت‌های Google Ads ایجاد می‌شود.

برای جلوگیری از این رفتار و برای اینکه خطا و پیام خطا قابل‌بررسی باشد، ویژگی muteHttpExceptions پارامترهای اختیاری را روی UrlFetchApp.fetch تنظیم کنید. برای مثال:

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

کدهای وضعیت رایج

  • 200 OK نشان‌دهنده موفقیت است. اگر پاسخ حاوی داده‌های موردانتظار نیست، این موارد را درنظر بگیرید:

    • برخی‌از میاناهای برنامه‌سازی کاربردی امکان مشخص کردن فیلدها، قالب پاسخ، یا هر دو را برای استفاده فراهم می‌کنند. برای جزئیات بیشتر، اسناد میانای برنامه‌سازی کاربردی را بررسی کنید.
    • یک میانای برنامه‌سازی کاربردی ممکن است چندین منبع داشته باشد که بتوان آن‌ها را فراخوانی کرد. برای تعیین اینکه آیا منبع دیگری ممکن است مناسب‌تر باشد و داده‌های موردنیاز شما را برگرداند، به اسناد مراجعه کنید.
    • ممکن است API از زمان نوشته شدن کد تغییر کرده باشد. برای شفاف‌سازی، به اسناد یا توسعه‌دهنده مراجعه کنید.
  • 400 Bad Request معمولاً به این معنی است که چیزی در قالب‌بندی یا ساختار درخواست ارسال‌شده به سرور درست نیست. درخواست را بررسی کنید و آن را با مشخصات API مقایسه کنید تا مطمئن شوید با انتظارات مطابقت دارد. برای جزئیات درباره نحوه بررسی درخواست‌ها، بررسی درخواست‌ها را ببینید.

  • 401 Unauthorized معمولاً به این معنی است که API بدون ارائه یا انجام موفقیت‌آمیز مجوز فراخوانی می‌شود.

    • اگر API از مجوز پایه استفاده می‌کند، مطمئن شوید که سرصفحه Authorization ساخته شده و در درخواست ارائه شده است.
    • اگر میانای برنامه‌سازی کاربردی از OAuth 2.0 استفاده می‌کند، مطمئن شوید کد دسترسی دریافت شده است و به‌عنوان رمزیاب دارنده ارائه می‌شود.
    • برای هرگونه تغییر دیگر در مجوز، مطمئن شوید که اعتبارنامه‌های لازم برای درخواست ارائه شده است.
  • 403 Forbidden نشان می‌دهد کاربر برای منبعی که درخواست می‌شود اجازه ندارد.

    • مطمئن شوید که اجازه‌های لازم به کاربر اعطا شده است، برای مثال، دسترسی به فایل در درخواست مبتنی بر فایل به کاربر داده شده باشد.
  • 404 Not Found یعنی منبع درخواستی وجود ندارد.

    • بررسی کنید نشانی وب استفاده‌شده برای نقطه پایان میانای برنامه‌سازی کاربردی درست باشد.
    • اگر منبعی را واکشی می‌کنید، بررسی کنید که منبع ارجاع‌شده وجود داشته باشد (برای مثال، اگر فایل برای میانای برنامه‌سازی کاربردی مبتنی بر فایل وجود داشته باشد).

بررسی درخواست‌ها

بازرسی درخواست‌ها زمانی مفید است که پاسخ‌های میانای برنامه‌سازی کاربردی نشان دهد درخواست به‌درستی شکل نگرفته است، برای مثال، کد وضعیت ۴۰۰. برای کمک به بررسی درخواست‌ها، 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;
    }
    

هنگام اجرای اسکریپت، جزئیات همه درخواست‌ها و پاسخ‌ها در کنسول ثبت می‌شود تا اشکال‌زدایی آسان‌تر شود.

[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