API های خارجی

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

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

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

مثال زیر از GitHub API برای جستجوی مخازن با 100 یا بیشتر ستاره استفاده می کند که "Apps Script" را ذکر کرده اند. این درخواست 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 و ارسال اعتبارنامه‌ها با درخواست‌های خود استفاده کنید:

• OAuth1 for Apps Script : سازگار با OAuth 1.0 و 1.0a.
• OAuth2 for Apps Script : سازگار با OAuth2.

با JSON کار کنید

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

اگر API درخواست شده یک پاسخ JSON خام را برای یک درخواست برمی گرداند، پاسخ رشته JSON را می توان با استفاده از روش HTTPResponse.getContentText() مشاهده کرد. هنگامی که این رشته بازیابی شد، به سادگی 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.