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 و ارسال اعتبارنامه‌ها به همراه درخواست‌های خود از آنها استفاده کنید:

کار با 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.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، XML مورد نظر را با استفاده از متدهای XmlService بسازید.

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.