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

إعداد ميزة "الردّ التلقائي على الويب الواردة" من خلال النقر على إضافة ميزة "الردّ التلقائي على الويب الواردة" واتّباع التعليمات من المفترض أن تُصدر العملية عنوان URL لاستخدامه في المراسلة.

إرسال طلب POST

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

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

إنشاء طلب

يجب اتّباع الخطوات التالية لإنشاء طلب مُعتمَد:

يمكنك إنشاء عبارة المرور من خلال دمج اسم المستخدم وكلمة المرور مع علامة colon (قوس عمودي)، على سبيل المثال 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، عليك شراء أرقام أو إضافتها إلى حساب الإصدار التجريبي. إضافة أرقام Sandbox التي يمكن استخدامها مع الحساب التجريبي
أضِف الرقم الذي سيظهر كمُرسِل والرقم المخصّص للمُستلِم.
استبدِل PLIVO_SRC_PHONE_NUMBER في النص البرمجي بأحد أرقام وضع الحماية التي تم تسجيلها للتو. يجب أن يتضمّن ذلك رمز البلد الدولي، مثلاً 447777123456 لرقم في المملكة المتحدة.

Twilio

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

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

‎OAuth 1.0

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

في حين أنّ المصادقة الأساسية لبروتوكول HTTP توفّر للمستخدم اسم مستخدم وكلمة مرور فقط، يسمح 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 أحادي الطرف

OAuth 2.0

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

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

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

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

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

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

في النص

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

تقديم طلبات البيانات من واجهة برمجة التطبيقات أرسِل رمز الوصول مع كل طلب.

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

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

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

التنفيذ

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

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

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

// 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 Playground

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

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

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

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

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 API.
الصِق نموذج النص البرمجي في نص برمجي جديد في "إعلانات Google".
الصِق نموذج مكتبة OAuth2 أسفل قائمة الرموز.
عدِّل النص البرمجي لكي يحتوي على القيم الصحيحة لمعرِّف العميل وسر العميل والرمز المميَّز لإعادة التحميل.

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

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

إنشاء نص برمجي في Apps Script

أنشئ نصًا برمجيًا جديدًا. سيُدرج العيّنة التالية 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;
}

ضبط Apps Script لتنفيذه

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

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

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

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

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

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

مثال على واجهة برمجة التطبيقات Google Natural 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 الكامل كيفية retrieving details of soccer matches، خاصةً مباريات الدوري الإنجليزي الممتاز. Soccer API هي إحدى مجموعة كبيرة من خلاصات الأخبار الرياضية التي تقدّمها شركة Sportradar.

إعداد حساب على Sportradar

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

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

ضمن "التطبيقات"، انقر على إنشاء تطبيق جديد. أدخِل اسمًا ووصفًا للتطبيق، وتجاهل حقل الموقع الإلكتروني.
اختَر فقط إصدار مفتاح جديد لإصدار Soccer Trial Europe v2.
انقر على تسجيل التطبيق.

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

الصِق نموذج النص البرمجي في نص برمجي جديد في "إعلانات 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 إلى النجاح. إذا لم تحتوي الاستجابة على data المتوقّعة، ننصحك بالآتي:
- تسمح بعض واجهات برمجة التطبيقات بتحديد الحقول و/أو تنسيق الاستجابة التي تريد استخدامها. يمكنك الاطّلاع على مستندات واجهة برمجة التطبيقات لمعرفة التفاصيل.
- قد تحتوي واجهة برمجة التطبيقات على موارد متعددة يمكن استدعاؤها. راجِع مستندات المساعدة لتحديد ما إذا كان قد يكون من الملائم استخدام مورد مختلف، والذي سيعرض البيانات التي تحتاج إليها.
- قد تكون واجهة برمجة التطبيقات قد تغيّرت منذ كتابة الرمز البرمجي. يمكنك الرجوع إلى مستندات التطبيق أو التواصل مع المطوّر للحصول على توضيح.
يشير الرمز 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;
}

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