API های خارجی

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

اتصال به API های عمومی

از سرویس UrlFetch برای ارسال مستقیم درخواست‌های API استفاده کنید.

مثال زیر از API گیت‌هاب برای جستجوی مخازنی با ۱۰۰ ستاره یا بیشتر که عبارت «اسکریپت برنامه‌ها» را ذکر کرده‌اند، استفاده می‌کند. این درخواست API نیازی به مجوز یا کلید API ندارد.

var query = '"Apps Script" stars:">=100"';
var url = 'https://api.github.com/search/repositories'
  + '?sort=stars'
  + '&q=' + encodeURIComponent(query);

var response = UrlFetchApp.fetch(url, {'muteHttpExceptions': true});
Logger.log(response);

درخواست‌ها را با استفاده از OAuth به سرویس‌ها ارسال کنید

APIهایی که از طرف کاربر عمل می‌کنند، معمولاً نیاز به مجوز دارند که اغلب از پروتکل OAuth استفاده می‌کنند. Apps Script پشتیبانی داخلی برای این پروتکل ارائه نمی‌دهد، اما کتابخانه‌های متن‌بازی وجود دارند که می‌توانید برای انجام جریان OAuth و ارسال اعتبارنامه‌ها به همراه درخواست‌های خود از آنها استفاده کنید:

احراز هویت با استفاده از حساب کاربری سرویس

برای فراخوانی یک API از Apps Script، ممکن است به دلایل زیر از احراز هویت حساب سرویس استفاده کنید:

  • عملکرد بهتر با API های Google Cloud
  • اتوماسیون‌ها و وظایف طولانی‌مدت
  • امنیت بهبود یافته (حداقل امتیاز)
  • مدیریت دسترسی متمرکز

برای استفاده از یک حساب سرویس در Apps Script، به بخش «احراز هویت به عنوان یک پروژه Apps Script با استفاده از حساب‌های سرویس» مراجعه کنید.

اتصال به سرویس‌های ابری گوگل

شما می‌توانید از متد ScriptApp.getIdentityToken() برای دریافت یک توکن هویت OpenID Connect (یک JSON Web Token یا JWT) برای کاربر فعال استفاده کنید. می‌توانید از این توکن برای احراز هویت با سرویس‌های Google Cloud مانند Cloud Run که برای پذیرش آن پیکربندی شده‌اند، استفاده کنید.

برای اطلاعات بیشتر، به «اتصال به سرویس‌های ابری گوگل» مراجعه کنید.

کار با JSON

کار با اشیاء JSON مشابه کار با XML است، با این تفاوت که تجزیه یا کدگذاری یک شیء JSON بسیار آسان‌تر است.

وقتی یک API یک پاسخ خام JSON برمی‌گرداند، با استفاده از متد HTTPResponse.getContentText به پاسخ رشته‌ای JSON دسترسی پیدا کنید. پس از بازیابی رشته، JSON.parse() برای تجزیه آن به یک شیء جاوا اسکریپت استفاده کنید.

// Make request to API and get response before this point.
var json = response.getContentText();
var data = JSON.parse(json);
Logger.log(data.title);

به طور مشابه، برای تبدیل یک شیء جاوا اسکریپت به یک رشته JSON برای بارگذاری درخواست، JSON.stringify() استفاده کنید.

var data = {
  'entry': {
    'group': {
      'title': 'Dog Skateboarding',
      'description': 'My dog gets some serious air'
    },
    'keywords': 'dog, skateboard'
  }
}
var payload = JSON.stringify(data);
// Make request to API with payload after this point.

تجزیه XML

اگر یک API خارجی برای یک درخواست، یک پاسخ خام XML برمی‌گرداند، با استفاده از متد HTTPResponse.getContentText() به پاسخ XML دسترسی پیدا کنید.

// Make request to API and get response before this point.
var xml = response.getContentText();
var doc = XmlService.parse(xml);

هنگام ارسال درخواست‌های XML به یک API، از متدهای XmlService برای ساخت XML مورد نظر برای ارسال استفاده کنید.

var root = XmlService.createElement('entry')
    .setAttribute('keywords', 'dog, skateboard');
var group = XmlService.createElement('group')
    .setAttribute('title', 'Dog Skateboarding')
    .setAttribute('description', 'My dog gets some serious air');
root.addContent(group);
var document = XmlService.createDocument(root);
var payload = XmlService.getPrettyFormat().format(document);
// Make request to API with payload after this point.