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

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

اضبط إعدادات Incoming Webhook بالنقر على Add Incoming WebHooks Integration واتّباع التعليمات. يجب أن تصدر العملية عنوان URL لاستخدامه في المراسلة.

إرسال طلب POST

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

  • ‫method: كما ذكرنا، يتم ضبط هذا الخيار تلقائيًا على GET، ولكننا هنا نتجاوزه ونضبطه على POST.
  • ‫payload: هذه هي البيانات التي سيتم إرسالها إلى الخادم كجزء من طلب POST. في هذا المثال، يتوقّع Slack عنصرًا متسلسلاً بتنسيق JSON كما هو موضّح في مستندات Slack. لهذا الغرض، يتم استخدام طريقة [JSON.stringify][json-stringify-url]، ويتم ضبط 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

إنشاء طلب

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

  1. أنشئ عبارة المرور من خلال دمج اسم المستخدم وكلمة المرور معًا باستخدام نقطتين، على سبيل المثال username:password.
  2. ترميز عبارة المرور باستخدام Base64، على سبيل المثال، تصبح username:password dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. أرفِق عنوان 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 هي خدمة تسهّل إرسال الرسائل القصيرة وتلقّيها من خلال واجهة برمجة التطبيقات الخاصة بها. يوضّح هذا النموذج كيفية إرسال الرسائل.

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

Twilio

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

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

‎OAuth 1.0

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

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

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

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

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

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

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

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

عمليات التفويض

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

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

التنفيذ

بالنسبة إلى جميع مسارات 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);

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

يُعدّ [منح بيانات اعتماد العميل][client-credentials-rfc] أحد أبسط أشكال مسار 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

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

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

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

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

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

رمز التفويض

استخدام OAuth Playground للحصول على رمز مميّز لإعادة التحميل

توفّر مساحة اختبار 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 للاطّلاع على التفاصيل الكاملة للإجراءات الأخرى التي يمكن تنفيذها.

إنشاء النص البرمجي
  1. أنشِئ مشروعًا جديدًا في وحدة تحكُّم Google Cloud، واحصل على معرّف العميل وسر العميل والرمز المميز لإعادة التحميل باتّباع الإجراء الموضّح في دليل &quot;إعلانات شبكة البحث 360&quot;، مع التأكّد من تفعيل Search Ads 360 API.
  2. الصق [نموذج النص البرمجي][search-ads-360-example] في نص برمجي جديد في "إعلانات Google".
  3. الصق [نموذج مكتبة OAuth2][oauth20-library-example] أسفل قائمة الرموز.
  4. عدِّل النص البرمجي ليتضمّن القيم الصحيحة لمعرّف العميل وسر العميل والرمز المميز لإعادة التحميل.

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

يوضّح هذا المثال تنفيذ دالة في "برمجة تطبيقات Google" باستخدام واجهة برمجة التطبيقات لتنفيذ برمجة تطبيقات Google. يتيح لك ذلك استدعاء "برمجة تطبيقات Google" من نصوص "إعلانات 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" للتنفيذ
  1. احفظ النص البرمجي.
  2. انقر على الموارد > مشروع Cloud Platform.
  3. انقر على اسم المشروع للانتقال إلى Google Cloud Console.
  4. انتقِل إلى واجهات برمجة التطبيقات والخدمات (APIs & Services).
  5. فعِّل واجهات برمجة التطبيقات المناسبة، وفي هذه الحالة واجهة برمجة تطبيقات Drive وواجهة برمجة تطبيقات تنفيذ "برمجة تطبيقات Google".
  6. أنشئ بيانات اعتماد OAuth من عنصر بيانات الاعتماد في القائمة.
  7. بالعودة إلى النص البرمجي، انشر النص البرمجي للتنفيذ من نشر > النشر كملف واجهة برمجة تطبيقات قابل للتنفيذ.
إنشاء نص "إعلانات Google" البرمجي
  1. الصِق نموذج النص البرمجي في نص برمجي جديد في "إعلانات Google".
  2. بالإضافة إلى ذلك، الصِق [نموذج مكتبة OAuth2][oauth20-library-example] أسفل قائمة الرموز.
  3. عدِّل النص البرمجي ليتضمّن القيم الصحيحة لمعرّف العميل وسر العميل والرمز المميز لإعادة التحميل.

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

من البدائل لأنواع إذن الوصول مفهوم حسابات الخدمة.

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

مثال على Google Natural Language API

توفّر [واجهة برمجة التطبيقات Natural Language API][natural-language-api-docs] [تحليل المشاعر][sentiment-analysis-api-docs] و[تحليل الكيانات][entity-analysis-api-docs] للنصوص.

يوضّح هذا المثال كيفية احتساب [المشاعر][sentiment-api-docs] لنص الإعلان، بما في ذلك العنوان أو الوصف. يوفّر ذلك مقياسًا لمدى إيجابية الرسالة وحجمها: أيهما أفضل، نبيع الكعك أو نبيع أفضل كعك في لندن؟ اشترِ اليوم.

إعداد النص البرمجي
  1. أنشِئ مشروعًا جديدًا في وحدة تحكُّم Google Cloud.
  2. فعِّل [واجهة برمجة تطبيقات اللغة الطبيعية][natural-language-api].
  3. فعِّل الفوترة للمشروع.
  4. [إنشاء حساب خدمة][create-service-account] نزِّل ملف JSON الخاص ببيانات الاعتماد.
  5. الصق [نموذج النص البرمجي][natural-language-example] في نص برمجي جديد في &quot;إعلانات Google&quot;.
  6. بالإضافة إلى ذلك، الصِق [نموذج مكتبة OAuth2][oauth20-library-example] أسفل قائمة الرموز.
  7. استبدِل القيم اللازمة:
    • ‫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

تسمح XmlService للنصوص البرمجية بتحليل البيانات واستخراجها من نصوص استجابة 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_schedules xmlns="http://schemas.sportradar.com/sportsapi/soccer/v4">
  <schedule>
     ...
  </schedule>
</schedule_schedules>

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

  • استخرِج سمة مساحة الاسم من المستند.
  • استخدِم مساحة الاسم هذه عند التنقّل بين العناصر الثانوية والوصول إليها.

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

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

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

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

<sport_event_status status="..." ... />

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

const statusElement = sportEventElement.getChild('sport_event_status', namespace);
const status = statusElement.getAttribute('status').getValue();

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

مثال على Sportradar

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

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

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

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

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

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

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

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

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

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

تحليل الردود

بشكلٍ تلقائي، سيتم طرح أي استجابة تُرجع خطأ (رمز حالة بقيمة 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(url, params)

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

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

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

ستسمح لك بفحص عناصر الطلب.

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

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

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

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

    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;
    }
    

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

[json-stringify-url]: //developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [client-credentials-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-4.4 [authorization-code-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 [oauth20-library-example]: /google-ads/scripts/docs/examples/oauth20-library [search-ads-360-example]: /google-ads/scripts/docs/examples/search-ads-360 [natural-language-api]: //console.developers.google.com/apis/api/language.googleapis.com/overview [create-service-account]: //console.developers.google.com/apis/credentials/serviceaccountkey [natural-language-example]: /google-ads/scripts/docs/examples/natural-language [natural-language-api-docs]: //cloud.google.com/natural-language/docs/ [sentiment-api-docs]: //cloud.google.com/natural-language/docs/reference/rest/v1beta2/Sentiment [sentiment-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-sentiment [entity-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-entities