تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

من الميزات القوية في النصوص البرمجية في إعلانات Google القدرة على الدمج مع البيانات والخدمات من واجهات برمجة التطبيقات التابعة لجهات خارجية

يتناول هذا الدليل المفاهيم التالية التي يمكن أن تساعدك في كتابة نصوص برمجية الربط بخدمات أخرى:

إنشاء طلبات HTTP: كيفية استخدام UrlFetchApp للوصول إلى من واجهات برمجة التطبيقات الخارجية.
المصادقة: تتناول بعض سيناريوهات المصادقة الشائعة.
تحليل الاستجابات: كيفية معالجة بيانات JSON وXML التي يتم عرضها

كما نقوم بتضمين عيّنات لرقم لواجهات برمجة التطبيقات الشائعة التي توضح هذه المفاهيم.

استرجاع البيانات باستخدام UrlFetchApp

UrlFetchApp الوظيفة الأساسية المطلوبة للتفاعل مع واجهات برمجة التطبيقات التابعة لجهات خارجية.

يوضح المثال التالي جلب بيانات الطقس من OpenWeatherMap: لقد اخترنا OpenWeatherMap بسبب نظام التفويض البسيط نسبيًا وواجهة برمجة التطبيقات.

تقديم طلب

تحدد وثائق OpenWeatherMap لطلب معلومات الطقس الحالية على النحو التالي:

http://api.openweathermap.org/data/2.5/weather?q=[location]&apikey=[apikey]

يقدم عنوان URL مثالنا الأول على التفويض: المعلمة apikey هي مطلوبة، وتكون القيمة فريدة لكل مستخدم. يتم الحصول على هذا المفتاح من خلال الاشتراك

بعد الاشتراك، يمكن إصدار طلب باستخدام المفتاح على النحو التالي:

const location = 'London,uk';
const apikey = 'da.......................81'; // Replace with your API key
const currentWeatherUrl = `http://api.openweathermap.org/data/2.5/weather?q=${location}&apiKey=${apiKey}`;
const response = UrlFetchApp.fetch(currentWeatherUrl);
console.log(response.getContentText());

ينتج عن تنفيذ هذا الرمز سلسلة طويلة من JSON. نص مكتوب في نافذة التسجيل في نصوص "إعلانات Google" البرمجية

تتمثل الخطوة التالية في تحويل هذا إلى تنسيق يمكن استخدامه في البرنامج النصي.

بيانات JSON

تقدّم العديد من واجهات برمجة التطبيقات ردودًا بتنسيق JSON. يمثل ذلك طريقة إنشاء تسلسل لكائنات JavaScript، مثل الكائنات والصفائف والأنواع الأساسية تمثيلها ونقلها كسلاسل.

لتحويل سلسلة JSON، مثل التي يتم عرضها من OpenWeatherMap—مرة أخرى في كائن JavaScript، استخدم طريقة JSON.parse. متابعة من المثال أعلاه:

const json = response.getContentText();
const weatherData = JSON.parse(json);
console.log(weatherData.name);
//  "London"

تحوّل الطريقة JSON.parse السلسلة إلى كائن لديه خاصية. name

يمكنك الاطّلاع على قسم تحليل الردود للحصول على مزيد من التفاصيل حول. تعمل مع ردود واجهة برمجة التطبيقات بتنسيقات مختلفة.

خطأ أثناء المعالجة

إنّ معالجة الأخطاء هي اعتبار مهم عند التعامل مع واجهات برمجة تطبيقات تابعة لجهات خارجية. في النصوص البرمجية لأن واجهات برمجة التطبيقات التابعة لجهات خارجية غالبًا ما تتغير بشكل متكرر وتؤدي قيم استجابة غير متوقعة، مثل:

قد يتغير عنوان URL أو معلَمات واجهة برمجة التطبيقات بدون علمك.
يمكن أن تنتهي صلاحية مفتاح واجهة برمجة التطبيقات (أو بيانات اعتماد المستخدم الأخرى).
ويمكن أن يتغير تنسيق الرد بدون إشعار.

رموز حالة HTTP

نظرًا لاحتمال حدوث استجابات غير متوقعة، يجب فحص بروتوكول HTTP رمز الحالة. بشكل افتراضي، ستعرِض الدالة UrlFetchApp استثناءً في حال العثور على رمز خطأ HTTP. إلى تغيير هذا السلوك، من الضروري تمرير معلمة اختيارية، كما هو الحال في المثال التالي:

const options = {
  muteHttpExceptions: true
}
const response = UrlFetchApp.fetch(url, options);
// Any status code greater or equal to 400 is either a client or server error.
if (response.getResponseCode() >= 400) {
  // Error encountered, send an email alert to the developer
  sendFailureEmail();
}

بنية الردّ

عند تغيير واجهات برمجة التطبيقات التابعة لجهات خارجية، لا يدرك المطوّرون غالبًا التغييرات التي قد تؤثر في النصوص البرمجية. على سبيل المثال، إذا كانت السمة name التي تم إرجاعها في مثال OpenWeatherMap إلى locationName، النصوص البرمجية سيفشل استخدام هذه الخاصية.

لهذا السبب، قد يكون من المفيد اختبار ما إذا كانت البنية المعروضة كما هو متوقع، على سبيل المثال:

const weatherData = JSON.parse(json);
if (weatherData && weatherData.name) {
  console.log('Location is : ' + name);
} else {
  console.log('Data not in expected format');
}

بيانات POST باستخدام UrlFetchApp

المثال التمهيدي من خلال OpenWeatherMap البيانات التي تم جلبها فقط. عادةً ما تكون طلبات البيانات من واجهة برمجة التطبيقات التي لا تتغير حالتها في جهاز التحكّم عن بُعد الخادم يستخدمون HTTP GET .

طريقة GET هي الطريقة التلقائية للطريقة UrlFetchApp. ومع ذلك، فإن بعض طلبات البيانات من واجهة برمجة التطبيقات مثل المكالمات إلى خدمة ترسل رسائل قصيرة SMS، فيلزم طرق أخرى، مثل POST أو PUT.

لتوضيح استخدام مكالمات POST مع UrlFetchApp، إليك المثال التالي التكامل مع Slack، وهو تطبيق مراسلة تعاوني تطبيق، لإرسال رسالة Slack إلى مستخدمي ومجموعات Slack.

إعداد Slack

يفترض هذا الدليل أنه سبق لك الاشتراك في حساب على Slack.

كما هو الحال مع OpenWeatherMap في المثال السابق، من الضروري الحصول على للسماح بإرسال الرسائل. يوفّر Slack عنوان URL فريدًا للسماح لك إرسال رسائل إلى فريقك، يُطلق عليه اسم الردّ التلقائي الوارد على الويب

إعداد الرد التلقائي الوارد على الويب بالنقر على إضافة دمج WebHooks واردة واتّباع التعليمات تشير رسالة الأشكال البيانية إلى إصدار عنوان URL لاستخدامه في المراسلة.

تقديم طلب POST

بعد إعداد الرد التلقائي الوارد على الويب، ما عليك سوى إجراء طلب POST. استخدام بعض الخصائص الإضافية في المعلمة options التي يتم تمريرها إلى UrlFetchApp.fetch:

method: كما ذكرنا، يتم ضبط القيمة التلقائية على GET، ولكننا نلغيها هنا اضبطها على POST.

payload: هذه هي البيانات التي سيتم إرسالها إلى الخادم كجزء من POST. طلبك. في هذا المثال، يتوقع Slack كائنًا متسلسلاً بتنسيق JSON. كما هو موضح في Slack ذات الصلة. لهذا السبب، JSON.stringify استخدام الطريقة، ويتم تعيين Content-Type على application/json.

  // Change the URL for the one issued to you from 'Setting up Slack'.
  const SLACK_URL = 'https://hooks.slack.com/services/AAAA/BBBB/CCCCCCCCCC';
  const slackMessage = {
    text: 'Hello, slack!'
  };

  const options = {
    method: 'POST',
    contentType: 'application/json',
    payload: JSON.stringify(slackMessage)
  };
  UrlFetchApp.fetch(SLACK_URL, options);

مثال Extended Slack

يوضح المثال أعلاه الحد الأدنى المطلوب لتفعيل الرسائل الواردة في Slack. إنّ يوضح النموذج الموسّع إنشاء وإرسال حملة أداء الحملة إبلاغ بالإضافة إلى بعض خيارات التنسيق والعرض.

رسالة واردة

الاطّلاع على تنسيق الرسالة في Slack لمزيد من التفاصيل حول رسائل Slack.

بيانات النموذج

تم توضيح المثال أعلاه باستخدام سلسلة JSON باعتبارها السمة payload. لطلب POST.

اعتمادًا على تنسيق payload، تعتمد ميزة "UrlFetchApp" نهجًا مختلفًا. لإنشاء طلب POST:

عندما تكون payload سلسلة، يتم إرسال وسيطة السلسلة على أنّها نص الطلب.
عندما تكون payload كائنًا، مثلاً خريطة للقيم:
```
{to: 'mail@example.com', subject:'Test', body:'Hello, World!'}
```
يتم تحويل أزواج المفتاح/القيمة إلى بيانات النموذج:
```
subject=Test&to=mail@example.com&body=Hello,+World!
```
يتم أيضًا ضبط عنوان Content-Type للطلب على application/x-www-form-urlencoded

تتطلب بعض واجهات برمجة التطبيقات استخدام بيانات النموذج عند إرسال طلبات POST، لذلك التحويل التلقائي من كائنات JavaScript إلى بيانات النموذج يكون مفيدًا في الاعتبار.

مصادقة HTTP الأساسية

HTTP الأساسي المصادقة هي واحدة من أبسط أشكال المصادقة ويستخدمها العديد من واجهات برمجة التطبيقات.

تتم المصادقة من خلال إرفاق اسم مستخدم وكلمة مرور مشفّرين بالحساب عناوين HTTP في كل طلب.

مصادقة HTTP الأساسية

إنشاء طلب

يجب اتّباع الخطوات التالية لتقديم طلب تمت مصادقته:

يمكنك إنشاء عبارة المرور من خلال جمع اسم المستخدم وكلمة المرور معًا نقطتان، على سبيل المثال username:password.
يعمل الترميز Base64 على ترميز عبارة المرور، ويصبح username:password في هذه الحالة dXNlcm5hbWU6cGFzc3dvcmQ=
أرفِق عنوان Authorization بالطلب، في النموذج Authorization: Basic <encoded passphrase>.

يوضّح المقتطف التالي كيفية تحقيق ذلك في نصوص "إعلانات Google" البرمجية:

const USERNAME = 'your_username';
const PASSWORD = 'your_password';
const API_URL = 'http://<place_api_url_here>';

const authHeader = 'Basic ' + Utilities.base64Encode(USERNAME + ':' + PASSWORD);
const options = {
  headers: {Authorization: authHeader}
}
// Include 'options' object in every request
const response = UrlFetchApp.fetch(API_URL, options);

نماذج المصادقة الأساسية

عيّنات التعليمات البرمجية على نموذجين يوضحان استخدام مصادقة HTTP الأساسية:

Plivo

Plivo هو خدمة تُسهِّل إرسال استلام رسائل SMS عبر واجهة برمجة التطبيقات يوضح هذا النموذج إرسال الرسائل.

يُرجى التسجيل لدى Plivo.
الصِق نموذج النص البرمجي في نص برمجي جديد في "إعلانات Google".
استبدل القيمتين PLIVO_ACCOUNT_AUTHID وPLIVO_ACCOUNT_AUTHTOKEN بـ من لوحة بيانات الإدارة.
يُرجى إدراج عنوان بريدك الإلكتروني كما هو محدّد في النص البرمجي لإشعار الأخطاء.
لاستخدام Plivo، يجب شراء أرقام أو إضافة أرقام إلى الفترة التجريبية. الحساب. إضافة أرقام وضع الحماية التي يمكن استخدامها مع الحساب التجريبي.
أضِف كلاً من الرقم الذي سيظهر كمُرسِل والرقم المستلِم. الصف.
يجب تحديث PLIVO_SRC_PHONE_NUMBER في النص البرمجي إلى أحد أرقام وضع الحماية مسجل للتو. يجب أن يشمل ذلك رمز البلد الدولي، مثال: 447777123456 لرقم على المملكة المتحدة.

Twilio

Twilio هي خدمة أخرى تُسهِّل إرسال البيانات استلام رسائل SMS عبر واجهة برمجة التطبيقات يوضح هذا النموذج إرسال الرسائل.

يُرجى التسجيل لدى Twillio.
لصق نموذج النص البرمجي إلى نص برمجي جديد في "إعلانات Google"
استبدل القيمتين TWILIO_ACCOUNT_SID وTWILIO_ACCOUNT_AUTHTOKEN بـ القيم المعروضة على صفحة وحدة تحكم الحساب.
استبدِل TWILIO_SRC_PHONE_NUMBER بالرقم من dashboard--هذه هي رقم مخوَّل من قِبل Twilio لإرسال الرسائل.

‎OAuth 1.0

تستخدم العديد من الخدمات الشائعة بروتوكول OAuth للمصادقة. يأتي بروتوكول OAuth في عدد من النكهات والإصدارات.

بينما عند استخدام مصادقة HTTP الأساسية، يمكن لمستخدم يشتمل بروتوكول OAuth على اسم مستخدم واحد وكلمة مرور واحدة فقط، فيتيح بروتوكول OAuth لتطبيقات الجهات الخارجية تم منح حق الوصول إلى حساب مستخدم وبياناته، باستخدام بيانات اعتماد خاصة بذلك تطبيق تابع لجهة خارجية. فضلاً عن ذلك، سيتم تحديد نطاق الوصول الخاصة بهذا التطبيق.

للحصول على خلفية عن بروتوكول OAuth 1.0، يمكنك الاطّلاع على دليل OAuth Core. وعلى وجه الخصوص، راجِع 6. المصادقة باستخدام OAuth. الثلاثي المراحل OAuth 1.0، تكون العملية كالتالي:

يحصل التطبيق ("المستهلك") على رمز مميز للطلب.
يفوّض المستخدم الرمز المميّز للطلب.
يتبادل التطبيق رمز الطلب برمز دخول.
بالنسبة إلى جميع طلبات الموارد اللاحقة، يتم استخدام رمز الدخول في ملف طلبك.

لكي تتمكن خدمات الجهات الخارجية من استخدام OAuth 1.0 بدون تفاعل المستخدم (على سبيل المثال: بما تتطلبه نصوص "إعلانات Google" البرمجية) الخطوتَين 1 و2 و3 غير ممكنة. لذلك، تصدر بعض الخدمات رمز دخول من إعداداتها مما يتيح للتطبيق الانتقال إلى الخطوة 4 مباشرة. يُعرف هذا باسم بروتوكول OAuth 1.0 الأحادي.

OAuth1

OAuth 1.0 في النصوص البرمجية على "إعلانات Google"

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

إعداد ضبط التطبيق لتمثيل النص البرمجي
حدِّد الأذونات التي سيتم تمديدها للنص البرمجي.
الحصول على مفتاح العميل وسر العميل ورمز الدخول وسر الوصول للاستخدام مع بروتوكول OAuth الأحادي.

OAuth 2.0

يتم استخدام OAuth 2.0 في واجهات برمجة التطبيقات الشائعة لتوفير الوصول إلى بيانات المستخدمين. مالك الحساب الذي يمنحه خدمة خارجية معيّنة إذنًا لتطبيقات محددة للسماح لها بالوصول إلى بيانات المستخدم. تشير رسالة الأشكال البيانية الفوائد هي أن المالك:

لا يلزم مشاركة بيانات اعتماد الحساب مع التطبيق.
التحكم في التطبيقات التي يمكنها الوصول إلى البيانات بشكلٍ فردي وإلى أي مدى. (على سبيل المثال، قد يكون إذن الوصول الممنوح للقراءة فقط أو لإذن مجموعة فرعية من البيانات).

لاستخدام الخدمات التي تدعم OAuth 2.0 في نصوص "إعلانات Google" البرمجية، هناك العديد من الخطوات:

خارج النص البرمجي

منح الإذن للنصوص البرمجية في "إعلانات Google" للوصول إلى بيانات المستخدمين من خلال واجهة برمجة التطبيقات التابعة لجهة خارجية. وفي معظم الحالات، سيشمل ذلك إعداد application في وحدة تحكُّم الخدمة التابعة لجهة خارجية. هذا التطبيق يُمثل نص إعلانات Google البرمجي.

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

في النص البرمجي

تفويض من خلال الخادم البعيد. استنادًا إلى نوع منح الخادم، ستحتاج إلى مجموعة مختلفة من الخطوات، المعروفة باسم التدفق إلى ولكن ستؤدي جميعها في النهاية إلى استخدام رمز دخول التي سيتم استخدامها لتلك الجلسة في جميع الطلبات اللاحقة.

إرسال طلبات البيانات من واجهة برمجة التطبيقات: مرِّر رمز الدخول مع كل طلب.

مسارات التفويض

يلبي كل نوع من أنواع المنح والتدفق المناسب سيناريوهات الاستخدام المختلفة. بالنسبة مثال، يتم استخدام تدفق مختلف عندما يشارك المستخدم في مشروع على عكس السيناريو الذي يلزم فيه تشغيل التطبيق في الخلفية دون وجود مستخدم.

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

التنفيذ

والهدف من كل تدفقات OAuth المختلفة هو الحصول على رمز دخول بعد ذلك خلال بقية الجلسة لمصادقة الطلبات.

نماذج مكتبة توضح كيفية المصادقة لكل نوع تدفق مختلف. كل من هذه كائنًا يحصل على رمز الدخول ويخزّنه ويسهل الطلبات التي تمت مصادقتها.

نمط الاستخدام العام هو:

// Authenticate using chosen flow type
const urlFetchObj = OAuth2.<flow method>(args);
// Make request(s) using obtained object.
const response1 = urlFetchObj.fetch(url1);
const response2 = urlFetchObj.fetch(url2, options);

منح بيانات اعتماد العميل

منح بيانات اعتماد العميل أحد الأشكال البسيطة لتدفق OAuth2، والذي يتبادل فيه التطبيق هو عبارة عن معرّف وسر،َين فريدَين للتطبيق مقابل إصدار رمز دخول لفترة محدودة

بيانات اعتماد العميل

// Access token is obtained and cached.
const authUrlFetch = OAuth2.withClientCredentials(
    tokenUrl, clientId, clientSecret, optionalScope));
// Use access token in each request
const response = authUrlFetch.fetch(url);
// ... use response

إعادة تحميل منح الرمز المميّز

يتشابه منح الرمز المميز لإعادة التحميل مع منح بيانات اعتماد العميل، بقدر ما سيؤدي طلب بسيط إلى الخادم إلى عرض رمز دخول يمكن استخدامه في الجلسة.

إعادة تحميل الرمز المميّز

الحصول على الرمز المميز للتحديث

يكمن الاختلاف في منح الرمز المميز للتحديث في أنه في حين أن تفاصيل المطلوبة لمنح بيانات اعتماد العميل، يتم الحصول عليها من إعدادات التطبيق (على سبيل المثال، في لوحة تحكم الخدمة)، يتم منح الرمز المميز للتحديث كجزء من عملية أكثر تعقيدًا، مثل رمز التفويض إذن، ما سيتطلّب من التفاعل:

رمز التفويض

استخدام "مساحة بروتوكول OAuth" للحصول على الرمز المميز لإعادة التحميل

يوفر ملعب OAuth2 واجهة مستخدم تسمح للمستخدم للتنقل عبر منح رمز التفويض من أجل الحصول على رمز مميز لإعادة التحميل.

يتيح لك زر الإعدادات في أعلى اليسار تحديد جميع المعلمات لاستخدامها في مسار OAuth، بما في ذلك:

نقطة نهاية التفويض: تُستخدَم كبداية لتدفق التفويض.
نقطة نهاية الرمز المميّز: تُستخدَم مع الرمز المميّز لإعادة التحميل للحصول على رمز دخول.
معرِّف العميل والسر: بيانات اعتماد التطبيق.

ساحة بروتوكول OAuth

استخدام نص برمجي للحصول على رمز مميز لإعادة التحميل

يتوفر بديل مستند إلى البرنامج النصي لإكمال التدفق في الرمز المميز للتحديث الجيل كعينة.

إعادة تحميل استخدام الرمز المميّز

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

const authUrlFetch = OAuth2.withRefreshToken(tokenUrl, clientId, clientSecret,
    refreshToken, optionalScope);
const response = authUrlFetch.fetch(url);
// ... use response

مثال على "إعلانات شبكة البحث 360"

"إعلانات شبكة البحث 360" هي مثال على واجهة برمجة تطبيقات يمكن استخدامها مع رمز مميّز لإعادة التحميل. في هذا النموذج، ينشئ النص البرمجي ويعرض بشكل تقريري. الرجوع إلى الإعلانات على شبكة البحث مرجع واجهة برمجة التطبيقات 360 للاطّلاع على التفاصيل الكاملة للإجراءات الأخرى التي يمكن تنفيذها.

إنشاء النص البرمجي

أنشئ مشروعًا جديدًا في وحدة تحكم واجهة برمجة التطبيقات، والحصول على معرِّف عميل وسر عميل ورمز مميز للتحديث من خلال اتّباع الإجراءات الواردة في دليل DoubleClick، مع التأكد من تمكين واجهة برمجة تطبيقات DoubleClick Search.
الصق العينة نص برمجي إلى نص برمجي جديد في "إعلانات Google"
لصق نموذج OAuth2 المكتبة أسفل الرموز البرمجية.
عدّل النص البرمجي ليتضمن القيم الصحيحة لمعرف العميل وسر العميل ثم إعادة تحميل الرمز المميز.

مثال على واجهة برمجة التطبيقات لتنفيذ برمجة التطبيقات

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

إنشاء نص برمجي لبرمجة التطبيقات

أنشئ نصًا برمجيًا جديدًا. سيسرد النموذج التالي 10 ملفات من Drive:

function listFiles() {
  const limit = 10;
  const files = [];
  const fileIterator = DriveApp.getFiles();
  while (fileIterator.hasNext() && limit) {
    files.push(fileIterator.next().getName());
    limit--;
  }
  return files;
}

ضبط برمجة التطبيقات لعملية التنفيذ

احفظ النص البرمجي.
انقر على الموارد > مشروع Cloud Platform.
انقر على اسم المشروع للانتقال إلى وحدة التحكم في واجهة برمجة التطبيقات.
انتقل إلى واجهات برمجة التطبيقات الخدمات:
تمكين واجهات برمجة التطبيقات المناسبة، وفي هذه الحالة Drive و التطبيقات تنفيذ النص البرمجي API.
أنشئ بيانات اعتماد OAuth من العنصر بيانات الاعتماد في القائمة.
بالرجوع إلى النص البرمجي، انشر النص البرمجي لتنفيذه من نشر > نشر كملف API قابل للتنفيذ.

إنشاء نص "إعلانات Google" البرمجي

الصق العينة نص برمجي إلى نص برمجي جديد في "إعلانات Google".
بالإضافة إلى ذلك، الصق نموذج OAuth2. المكتبة أسفل الرموز البرمجية.
عدّل النص البرمجي ليتضمن القيم الصحيحة لمعرف العميل وسر العميل ثم إعادة تحميل الرمز المميز.

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

هناك بديل لأنواع المنح المذكورة أعلاه وهو مفهوم الخدمة الحسابات.

تختلف حسابات الخدمة عن الحسابات المذكورة أعلاه في أنّها لا تُستخدم للوصول إلى حسابات المستخدمين. البيانات: بعد المصادقة، يتم تقديم الطلبات من خلال حساب الخدمة نيابةً عن من التطبيق، وليس كالمستخدم الذي قد يملك المشروع. على سبيل المثال، إذا حساب الخدمة هو استخدام Drive API لإنشاء ملف، وهذا من شأنه أن إلى حساب الخدمة، ولا يمكن الوصول إليها تلقائيًا من خلال مالك المشروع.

مثال على واجهة برمجة تطبيقات اللغة الطبيعية من Google

توفر واجهة برمجة التطبيقات للّغات الطبيعية الآراء التحليل الكيان التحليل للنص.

يوضح هذا المثال حساب الآراء لنص الإعلان، بما في ذلك العنوان أو الوصف. يوفر هذا مقياسًا مدى إيجابية الرسالة وحجم الرسالة: أيهما أفضل نحن نبيع الكعك أو نبيع أفضل الكعك في دبي. هل تريد الشراء اليوم؟

إعداد النص البرمجي

إنشاء مشروع جديد في وحدة تحكم واجهة برمجة التطبيقات
تفعيل اللغة الطبيعية واجهة برمجة التطبيقات
تفعيل الفوترة للمشروع
إنشاء خدمة الحساب. نزِّل ملف JSON لبيانات الاعتماد.
الصق العينة النص البرمجي إلى لغة النص البرمجي في "إعلانات Google"
بالإضافة إلى ذلك، الصق نموذج OAuth2. المكتبة أسفل الرموز البرمجية.
استبدل القيم الضرورية:
- serviceAccount: عنوان البريد الإلكتروني لحساب الخدمة مثلاً xxxxx@yyyy.iam.gserviceaccount.com
- key: المفتاح من ملف JSON الذي تم تنزيله عند إنشاء الخدمة الحساب. يبدأ في -----BEGIN PRIVATE KEY... وينتهي في ...END PRIVATE KEY-----\n.

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

يمكن لواجهات برمجة التطبيقات عرض بيانات بمجموعة من التنسيقات. وأبرزها هي تنسيق XML وJSON.

JSON

يكون تنسيق JSON أسهل من تنسيق XML في العمل بشكل صحيح. ومع ذلك، لا تزال هناك بعض المشاكل التي يمكن أن تظهر.

التحقّق من صحة الردّ

وبعد الحصول على رد ناجح من الاتصال بواجهة برمجة التطبيقات، فإن النموذج الخطوة التالية هي استخدام JSON.parse لتحويل سلسلة JSON إلى JavaScript. الخاص بك. في هذه المرحلة، من المنطقي التعامل مع الحالة التي يكون فيها تحليل الأخطاء:

const json = response.getContentText();
try {
  const data = JSON.parse(json);
  return data;
} catch(e) {
  // Parsing of JSON failed - handle error.
}

أيضًا، إذا لم تكن واجهة برمجة التطبيقات تحت سيطرتك، ضع في اعتبارك أن بنية قد تتغير الاستجابة، وقد لا تتوفر خصائص بعد ذلك:

// Less good approach
// Assumes JSON was in form {"queryResponse": ...} when parsed.
const answer = data.queryResponse;

// Better approach
if (data && data.queryResponse) {
  const answer = data.queryResponse;
} else {
  // Format of API response has changed - alert developer or handle accordingly
}

XML

التحقّق من الصحة

لا يزال XML تنسيقًا شائعًا لإنشاء واجهات برمجة التطبيقات. ردّ من طلب بيانات من واجهة برمجة التطبيقات تحليلها باستخدام XmlService parse :

const responseText = response.getContentText();
try {
  const document = XmlService.parse(responseText);
} catch(e) {
  // Error in XML representation - handle accordingly.
}

بينما يرصد XmlService.parse الأخطاء في ملف XML ويقدّم الاستثناءات. ومن ثم، لا يوفر إمكانية التحقق من صحة XML مقابل Google.

عنصر الجذر

وفقًا للتحليل الناجح لمستند XML، يتم الحصول على العنصر الجذر. باستخدام طريقة getRootElement():

const document = XmlService.parse(responseText);
const rootElement = document.getRootElement();

مساحات الاسم

في المثال التالي، تعرض Sportradar API يُستخدم للحصول على نتائج كرة القدم لمباريات محددة. تستغرق استجابة XML بالتنسيق التالي:

<schedule xmlns="http://feed.elasticstats.com/schema/soccer/sr/v2/matches-schedule.xsd">
  <matches>
     ...
  </matches>
</schedule>

لاحظ كيف يتم تحديد مساحة الاسم في العنصر الجذر. لهذا السبب، من أجل:

استخرِج سمة مساحة الاسم من المستند.
يمكنك استخدام مساحة الاسم هذه عند اجتياز العناصر الثانوية والوصول إليها.

يوضّح النموذج التالي كيفية الوصول إلى عنصر <matches> في العنصر أعلاه. مقتطف المستند:

const document = XmlService.parse(xmlText);
const scheduleElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = scheduleElement.getNamespace();
const matchesElement = scheduleElement.getChild('matches', namespace);

الحصول على القيم

بالنظر إلى عينة من جدول كرة القدم:

<match status="..." category="..." ... >
  ...
</match>

ويمكن استرداد السمات، على سبيل المثال:

const status = matchElement.getAttribute('status').getValue();

يمكن قراءة النص الموجود داخل أحد العناصر باستخدام getText()، ولكن هذه ستكون مسلسل حيث يوجد العديد من العناصر الثانوية النصية لأحد العناصر. ضع في اعتبارك استخدام getChildren() والتكرار على كل عنصر ثانوي في الحالات التي برسائل نصية من المحتمل أن تكون الأطفال.

مثال Sportradar

يعمل هذا Sportradar بالكامل مثال يوضّح استرداد تفاصيل مباريات كرة القدم، وتحديدًا الدوري الإنجليزي الممتاز تطابق. Soccer API هي واحدة من مجموعة كبيرة من الخلاصات الرياضية التي تقدمها Sportradar.

إعداد حساب Sportradar

انتقِل إلى الموقع الإلكتروني للمطوّرين منSportradar.
سجِّل للحصول على حساب تجريبي.
بعد التسجيل، سجِّل الدخول إلى حسابك.
بعد تسجيل الدخول، انتقِل إلى MyAccount.

تفصل Sportradar الألعاب الرياضية المختلفة في واجهات برمجة تطبيقات مختلفة. على سبيل المثال، إمكانية شراء إمكانية الوصول إلى Soccer API ولكن ليس Tennis API. على كل التطبيق الذي تنشئه يمكن أن يرتبط برياضات مختلفة مفاتيح مختلفة.

ضمن "التطبيقات"، انقر على إنشاء تطبيق جديد. منح التطبيق كاسم ووصف، وتتجاهل حقل موقع الويب.
اختَر فقط إصدار مفتاح جديد للإصدار 2 من "كرة القدم" التجريبي.
انقر على تسجيل التطبيق.

وبعد نجاح الإجراء، من المفترض أن يؤدي ذلك إلى إنشاء صفحة تحتوي على مفتاح واجهة برمجة التطبيقات الجديد.

لصق نموذج النص البرمجي إلى نص برمجي جديد في "إعلانات Google"
استبدل مفتاح واجهة برمجة التطبيقات في القائمة بالمفتاح الذي تم الحصول عليه أعلاه، وعدِّل حقل عنوان البريد الإلكتروني.

تحديد المشاكل وحلّها

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

العملاء الذين يصدرون طلبات إلى الخادم بتنسيق لا تتوقّعه واجهة برمجة التطبيقات
العملاء الذين يتوقعون تنسيق استجابة مختلفًا عن التنسيق الذي يظهر.
العملاء الذين يستخدمون رموزًا مميّزة أو مفاتيح غير صالحة، أو قيمًا متبقّية كعناصر نائبة
وصول العملاء إلى حدود الاستخدام.
العملاء الذين يقدمون معلَمات غير صالحة

تعد خطوة أولى جيدة في تحديد السبب في كل هذه الحالات وغيرها التحقق من تفاصيل الرد التي تسببت في حدوث الخطأ.

تحليل الردود

وبشكل افتراضي، أي استجابة تعرض خطأ (حالة الرمز من 400 أو أكثر) سوف من خلال محرك النصوص البرمجية في إعلانات Google.

لمنع هذا السلوك، والسماح بعرض الخطأ ورسالة الخطأ تم فحصه، اضبط الخاصية muteHttpExceptions للمعلمات الاختيارية على UrlFetchApp.fetch على سبيل المثال:

const params = {
  muteHttpExceptions: true
};
const response = UrlFetchApp.fetch(url, params);
if (response.getResponseCode() >= 400) {
  // ... inspect error details...
}

رموز الحالات الشائعة

يشير 200 OK إلى النجاح. إذا لم يكن الرد يحتوي على القيمة المتوقعة البيانات، ضع في اعتبارك ما يلي:
- تسمح بعض واجهات برمجة التطبيقات بتحديد الحقول و/أو تنسيق الاستجابة استخدامها. لمزيد من التفاصيل حول هذا الأمر، يمكنك مراجعة مستندات واجهة برمجة التطبيقات.
- قد تضم واجهة برمجة التطبيقات موارد متعددة يمكن استدعاءها. الرجوع إلى وثائق لتحديد ما إذا كان مورد مختلف قد يكون للاستخدام، وسيعرض البيانات التي تحتاجها.
- ربما تغيرت واجهة برمجة التطبيقات منذ كتابة الرمز. الرجوع إلى المستندات أو المطور للتوضيح.
تعني العلامة 400 Bad Request عادةً أنّ هناك خطأ ما في تنسيق أو بنية الطلب المرسل إلى الخادم. فحص طلبه ومقارنته بمواصفات واجهة برمجة التطبيقات لضمان توافقه مع وتوقعاتهم. راجِع فحص الطلبات للحصول على تفاصيل عن كيفية فحص الطلبات.
تعني 401 Unauthorized عادةً أنّه يتم طلب واجهة برمجة التطبيقات بدون تقديم أو إجراء التفويض بنجاح.
- إذا كانت واجهة برمجة التطبيقات تستخدم تفويضًا أساسيًا، تأكَّد من أنّ عنوان Authorization يتم إنشاؤه وتقديمه في الطلب.
- إذا كانت واجهة برمجة التطبيقات تستخدم OAuth 2.0، تأكَّد من الحصول على رمز الدخول. ويتمّ توفيره على أنّه رمز حامل مميّز.
- بالنسبة إلى أي اختلافات أخرى في التفويض، تأكَّد من المعلومات تقديم بيانات الاعتماد الخاصة بالطلب.
403 Forbidden يشير إلى أن المستخدم ليس لديه إذن للوصول إلى المورد المطلوبة.
- تأكَّد من منح المستخدم الأذونات اللازمة، مثل لمنح المستخدم حق الوصول إلى ملف في طلب قائم على ملف.
تعني عبارة "404 Not Found" أنّ المورد المطلوب غير متوفّر.
- تحقَّق من صحة عنوان URL المستخدَم لنقطة نهاية واجهة برمجة التطبيقات.
- في حال استرجاع مورد، تأكَّد من توفُّر المورد الذي تتم الإشارة إليه. (على سبيل المثال، إذا كان الملف موجودًا لواجهة برمجة تطبيقات مستندة إلى الملف).

فحص الطلبات

يكون فحص الطلبات مفيدًا عندما تشير ردود واجهة برمجة التطبيقات إلى سوء الطلب على سبيل المثال، رمز حالة 400. للمساعدة في فحص الطلبات، يُرجى UrlFetchApp. له طريقة مصاحبة لطريقة fetch()، تُسمى getRequest()

وبدلاً من إرسال طلب إلى الخادم، تنشئ هذه الطريقة الطلب التي كان سيتم إرسالها ثم تُرجعها. هذا يسمح للمستخدم وفحص عناصر الطلب للتأكد من أن الطلب يبدو صحيحًا.

على سبيل المثال، إذا كانت بيانات النموذج في طلبك تتكون من العديد من السلاسل التي يتم إنشاء تسلسل لها معًا، قد يكمن الخطأ في الدالة التي أنشأتها لإنشاء هذا النموذج البيانات. في أبسط الحالات:

const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...

بفحص عناصر الطلب.

تسجيل الطلبات والردود

للمساعدة في العملية الكاملة لفحص الطلبات والردود واجهة برمجة التطبيقات التابعة لجهة خارجية، يمكن استخدام دالة المساعدة التالية استبدال UrlFetchApp.fetch()، لتسجيل كل من الطلبات والردود.

استبدِل جميع تكرارات UrlFetchApp.fetch() في الرمز بـ logUrlFetch()

أضف الدالة التالية إلى نهاية النص البرمجي.

function logUrlFetch(url, opt_params) {
  const params = opt_params || {};
  params.muteHttpExceptions = true;
  const request = UrlFetchApp.getRequest(url, params);
  console.log('Request:       >>> ' + JSON.stringify(request));
  const response = UrlFetchApp.fetch(url, params);
  console.log('Response Code: <<< ' + response.getResponseCode());
  console.log('Response text: <<< ' + response.getContentText());
  if (response.getResponseCode() >= 400) {
    throw Error('Error in response: ' + response);
  }
  return response;
}

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