واجهات برمجة التطبيقات الخارجية

يمكن أن تتفاعل "برمجة تطبيقات Google" مع واجهات برمجة التطبيقات من جميع أنحاء الويب. يوضّح هذا الدليل كيفية استخدام أنواع مختلفة من واجهات برمجة التطبيقات في النصوص البرمجية.

الاتصال بواجهات برمجة التطبيقات العامة

يمكنك استخدام خدمة UrlFetch لتقديم طلبات إلى واجهة برمجة التطبيقات مباشرةً.

يستخدم المثال التالي GitHub API للبحث عن مستودعات تحتوي على 100 نجمة أو أكثر وتتضمّن الإشارة إلى "برمجة تطبيقات". لا يتطلّب طلب البيانات من واجهة برمجة التطبيقات هذا تفويضًا أو مفتاح واجهة برمجة تطبيقات.

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

تتطلّب واجهات برمجة التطبيقات التي تعمل بالنيابة عن المستخدم عادةً الحصول على إذن، وغالبًا ما يتم ذلك باستخدام بروتوكول OAuth. لا توفّر "برمجة تطبيقات Google" دعمًا مدمجًا للبروتوكول، ولكن تتوفّر مكتبات مفتوحة المصدر يمكنك استخدامها لتنفيذ عملية OAuth وإرسال بيانات الاعتماد مع طلباتك:

المصادقة باستخدام حساب خدمة

لاستدعاء واجهة برمجة تطبيقات من Apps Script، يمكنك اختيار استخدام مصادقة حساب الخدمة لأي من الأسباب التالية:

  • أداء أفضل باستخدام Cloud APIs في Google Cloud
  • عمليات التشغيل الآلي والمهام الطويلة الأمد
  • تحسين الأمان (منح أقل أذونات ممكنة)
  • إدارة أذونات الوصول المركزية

لاستخدام حساب خدمة في برمجة تطبيقات، اطّلِع على مقالة المصادقة كمشروع برمجة تطبيقات باستخدام حسابات الخدمة.

الربط بخدمات Google Cloud

يمكنك استخدام طريقة ScriptApp.getIdentityToken() للحصول على رمز مميّز لهوية اتصال OpenID (رمز JSON المميّز للويب أو JWT) للمستخدم الفعلي. يمكنك استخدام هذا الرمز المميز للمصادقة مع خدمات Google Cloud، مثل Cloud Run، التي تم ضبطها لقبول هذا الرمز.

لمزيد من المعلومات، يُرجى الاطّلاع على الاتصال بخدمات Google Cloud.

التعامل مع JSON

إنّ التعامل مع عناصر JSON يشبه التعامل مع XML، إلا أنّ تحليل عنصر JSON أو ترميزه أسهل بكثير.

إذا كانت واجهة برمجة التطبيقات المطلوبة تعرض استجابة 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);

وبالمثل، لإنشاء تمثيل سلسلة لكائن JavaScript من أجل تقديم طلب، استخدِم 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

إذا عرضت واجهة برمجة تطبيقات خارجية استجابة XML أولية لطلب، يمكنك الوصول إلى استجابة XML باستخدام الطريقة HTTPResponse.getContentText().

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

عند إرسال طلبات XML إلى إحدى واجهات برمجة التطبيقات، أنشئ 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.