تمت ترجمة هذه الصفحة بواسطة 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);

مثال على 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);

Plivo

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

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

Twilio

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

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

‎OAuth 1.0

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

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

للاطّلاع على معلومات أساسية عن OAuth 1.0، راجِع دليل OAuth الأساسي. وعلى وجه الخصوص، راجع 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" للوصول إلى بيانات المستخدمين من خلال واجهة برمجة التطبيقات التابعة لجهة خارجية. وفي معظم الحالات، يتضمّن ذلك إعداد تطبيق في وحدة التحكّم الخاصة بخدمة الجهة الخارجية. يمثِّل هذا التطبيق نصّك البرمجي في "إعلانات 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" هي مثال على واجهة برمجة تطبيقات يمكن استخدامها مع الرمز المميّز لإعادة التحميل. في هذا النموذج، ينشئ النص البرمجي تقريرًا ويعرضه. ويمكنك الرجوع إلى مرجع Search Ads 360 API للاطّلاع على التفاصيل الكاملة عن الإجراءات الأخرى التي يمكن تنفيذها.

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

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

مثال على Apps Script Execution API

يوضّح هذا المثال تنفيذ دالة في لغة "برمجة تطبيقات 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;
}

إعداد "برمجة تطبيقات Google" للتنفيذ

احفظ النص البرمجي.
انقر على الموارد > مشروع Cloud Platform.
انقر على اسم المشروع للانتقال إلى وحدة تحكّم واجهة برمجة التطبيقات.
انتقِل إلى APIs & Services (واجهات برمجة التطبيقات والخدمات).
فعِّل واجهات برمجة التطبيقات المناسبة، مثل واجهة برمجة تطبيقات Drive وواجهة برمجة التطبيقات لبرمجة التطبيقات.
أنشئ بيانات اعتماد OAuth من العنصر بيانات الاعتماد في القائمة.
ارجع إلى النص البرمجي، انشر النص البرمجي للتنفيذ من نشر > نشر كواجهة برمجة تطبيقات قابلة للتنفيذ.

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

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

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

يُعد مفهوم حسابات الخدمة بديلاً عن أنواع المنح الموضحة أعلاه.

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

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

توفّر normal language API إمكانية تحليل الآراء وتحليل الكيان للنص.

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

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

أنشئ مشروعًا جديدًا في وحدة تحكم واجهة برمجة التطبيقات.
تفعيل واجهة برمجة التطبيقات لللغة الطبيعية
تفعيل الفوترة للمشروع
أنشِئ حساب خدمة. نزِّل ملف 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 من خلال مخطّط.

عنصر الجذر

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

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

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

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

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

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

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

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

تحليل الردود

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

لمنع هذا السلوك والسماح بفحص الخطأ ورسالة الخطأ، اضبط السمة 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;
}

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