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

يمكن أن تتفاعل "برمجة تطبيقات 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. لا توفّر "برمجة التطبيقات" دعمًا مدمجًا للبروتوكول، ولكن تتوفّر مكتبات مفتوحة المصدر يمكنك استخدامها لتنفيذ عملية OAuth وإرسال بيانات الاعتماد مع طلباتك:

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

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

  • أداء أفضل باستخدام واجهات برمجة التطبيقات من 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() لتحليلها إلى عنصر JavaScript.

// 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 لطلب حمولة، استخدِم 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 إلى واجهة برمجة تطبيقات، استخدِم طرق 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.