كيفية استدعاء واجهة برمجة تطبيقات API عامة في جداول بيانات جوجل باستخدام Apps Script

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

وسوف نستمر في العمل مع فئات SpreadsheetApp، و Spreadsheet، و Sheet، و Range التي تعرفنا عليها في المقالات السابقة من هذا الدليل.

هذا هو المقال الرابع في دليل تعلم أساسيات برمجة التطبيقات مع جداول بيانات جوجل، وقبل البدء تأكد من إكمال المقالات السابقين:

1. أساسيات برمجة التطبيقات Apps Script.
2. جداول البيانات والأوراق والنطاقات.
3. العمل مع البيانات.

ماذا ستتعلم

1. كيفية سحب بيانات كائن JSON ومعالجتها من مصدر API عام.
2. كتابة بيانات الـ API في جدول بيانات

ماذا ستحتاج

• فهم موضوعات Apps Script الأساسية التي استكشفناها في المقالين السابقين من هذا الدليل.
• الإلمام الأساسي بمحرر الشيفرات البرمجية Apps Script.
• الإلمام الأساسي بجداول بيانات Google.
• الإلمام الأساسي بلغة البرمجة JavaScript وصنف 'String' الخاص به.

الإعداد للعمل

هذا المقال يعتبر استكمالاً للمقال السابق "العمل مع البيانات"، وستتعلم فيه كيفية زيادة تحسين مجموعة البيانات الموجودة داخل جدول البيانات الذي أنشأته باسم "معالجة البيانات والقوائم المخصصة"، فسوف تعمل على ملء الخلايا الفارغة داخل هذا الجدول ببيانات مستمدة من واجهة برمجة تطبيقات عامة API. لذلك سوف نستكمل التدريبات في هذا المقال باستخدام جدول البيانات "معالجة البيانات والقوائم المخصصة"، ومشروع Apps Script الذي أنشأناه باسم "Data Manipulation and Custom Menus" أيضًا، فإن كنت متابع لهذه السلسلة من البداية فليس مطلوب منك عمل أي شيء، فقط استكمل تنفيذ التدريبات الموجودة بهذا المقال باستخدام جدول البيانات "معالجة البيانات والقوائم المخصصة" الذي استخدمته في المقال السابق "العمل مع البيانات".

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

نظرة عامة: الحصول على البيانات من واجهات برمجة التطبيقات العامة API

لقد نجحت حتى الآن في تحسين مجموعة البيانات الخاصة بك لإصلاح بعض مشكلات تنسيق العنوان والمؤلف، لكن مجموعة البيانات لا تزال تفتقد بعض المعلومات كما هو موضح أدناه:

سوف تحتاج للحصول على البيانات المفقودة إلى مصدر آخر، ويمكنك عمل ذلك في Apps Script عن طريق طلب معلومات من واجهات برمجة التطبيقات الخارجية API التي يمكنها توفير بيانات إضافية.

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

وسوف يعلمك هذا القسم كيفية:

• طلب بيانات الكتاب من مصدر خارجي لواجهة برمجة التطبيقات.
• استخراج معلومات العنوان والمؤلف من البيانات التي تم إرجاعها ووضعها في الخلايا الشاغرة بجدول البيانات الخاص بك.

إحضار البيانات الخارجية باستخدام UrlFetch

سوف تأخذ الدالة المساعدة ()_fetchBookData معاملًا واحدًا هو رقم ISBN أو الرقم العالمي الموحد للكتاب وهو مكون من 13 رقمًا كمعامل، ثم تتصل بواجهة برمجة التطبيقات العامة "Open Library API" ثم تعيد بيانات حول هذا الكتاب في كائن JSON.

اقتباس

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

التطبيق

يمكنك إنشاء هذه الدالة المساعدة بإضافة الدالة التالية إلى نهاية مشروع النص البرمجي في محرر Apps Script:

/**
 دالة مساعدة لاسترداد بيانات الكتب *
 من واجهة برمجة التطبيقات العامة "Open Library API" *
 *
 * @param {number} ISBN - الرقم العالمي الموحد للكتاب الذي تريد العثور عليه
 * @return {object} بيانات الكتاب بتنسيق جيسون
 */
function fetchBookData_(ISBN){
 الاتصال بواجهة برمجة التطبيقات العامة API //
  var url = "https://openlibrary.org/api/books?bibkeys=ISBN:"
      + ISBN + "&jscmd=details&format=json";
  var response = UrlFetchApp.fetch(
      url, {'muteHttpExceptions': true});

 تقديم طلبًا إلى API والحصول على استجابة قبل هذه النقطة //
  var json = response.getContentText();
  var bookData = JSON.parse(json); 

  إرجاع البيانات التي نهتم بها فقط //
  return bookData['ISBN:' + ISBN];
}

احفظ مشروع نصك البرمجي.

اقتباس

تنويه: في Apps Script تعتبر أسماء الدوال المنتهية بـ _ (شرطة سفلية) خاصة، فلا تستطيع السكربتات الأخرى استدعاء هذه الدوال، لذلك إذا كنت تعرف أن الدالة ستستخدم فقط بواسطة السكربت الحالي فقط، فمن الأفضل إنهاء اسم الدالة بـ _ (شرطة سفلية)

مراجعة الشيفرة البرمجية

تنقسم هذه الشيفرة البرمجية إلى قسمين رئيسيين:

1. طلب API

في السطرين الأولين تتصل الدالة ()_fetchBookData بواجهة برمجة التطبيقات العامة "Open Library API" باستخدام نقطة نهاية عنوان URL لواجهة برمجة التطبيقات API، وخدمة جلب عنوان URL لبرمجة التطبيقات Apps Script.

المتغير url هو مجرد عنوان ويب يشير إلى موقع على خوادم Open Library، ويتضمن هذا المتغير ثلاثة معاملات، هي: bibkeys و jscmd و format، تخبر خوادم Open Library بالمعلومات التي تطلبها وكيفية هيكلة الاستجابة، ففي مثالنا أنت تقدم رقم ISBN أو الرقم العالمي للكتاب وتطلب عرض معلومات مفصلة عنه بتنسيق JSON.

بمجرد إنشاء سلسلة URL تُرسل الشيفرة البرمجية طلبًا إلى الموقع ويتلقى ردًا، ويحدث ذلك باستخدام التابع (UrlFetchApp.fetch(url, params يرسل طلب معلومات إلى عنوان URL الخارجي الذي تقدمه ويخزن الاستجابة الناتجة في المتغير response بالإضافة إلى عنوان URL، وتعيّن الشيفرة البرمجية المعامل الاختياري "muteHttpExceptions" إلى القيمة "true"، ويعني هذا الإعداد أن الشيفرات البرمجية الخاصة بك لن تتوقف إذا نتج عن الطلب خطأ في واجهة برمجة التطبيقات، وبدلاً من ذلك تُرجع استجابة الخطأ.

يُرجع الطلب كائن HTTPResponse يُخزن في المتغير response، ويتضمن الكائن HTTPResponse معرف الاستجابة ورؤوس HTTP ومحتوى الاستجابة الرئيسي، أما المعلومات ذات الأهمية هنا في محتوى JSON الرئيسي، لذلك يجب على الشيفرة البرمجية استخراج ذلك ثم تحليل JSON لتحديد موقع المعلومات المطلوبة وإرجاعها.

2. تحليل استجابة API وإرجاع المعلومات التي تهمك

في الأسطر الثلاثة الأخيرة من الشيفرة البرمجية، يعمل التابع ()HTTPResponse.getContentText على إرجاع المحتوى الرئيسي من المتغير response كسلسلة بتنسيق JSON، ثم يعمل التابع (JSON.parse(jsonString على تحويل سلسلة JSON إلى كائن JavaScript إذ يمكن استخراج أجزاء مختلفة من البيانات بسهولة.

أخيرًا تعمل الدالة على إرجاع البيانات المقابلة لرقم ISBN أو الترقيم العالمي للكتاب.

النتائج

الآن بعد أن نفذت الدالة ()_fetchBookData يمكنك استخدامها للمساعدة في ملء الخلايا الشاغرة في جدول البيانات، لكن إن استخدمتها الآن سوف تحصل على رسالة خطأ لأننا لم ننشىء بعد الدالة ()fillInTheBlanks المرتبطة بالقائمة الفرعية المخصصة "ملء الخلايا الفارغة بالعنوان والمؤلف".

كتابة بيانات الواجهة API في جدول بيانات

يمكنك الآن إنشاء الدالة ()fillInTheBlanks التي تنفذ ما يلي:

1. تحديد بيانات العنوان والمؤلف المفقودة ضمن نطاق البيانات النشط.
2. استرجاع البيانات المفقودة لكتاب معين عن طريق استدعاء Open Library API باستخدام التابع ()_fetchBookData.
3. تحديث قيم العنوان والمؤلف المفقودة في الخلايا الخاصة بهما.

التطبيق

يمكنك إنشاء هذه الدالة من خلال إضافة الدالة التالية إلى نهاية مشروع النص البرمجي في محرر Apps Script:

/**
 يملأ بيانات العنوان والمؤلف المفقودة *
 باستخدام استدعاءات Open Library API *
 */ 
function fillInTheBlanks(){
  تعريف الثوابت التي تحدد رقم فهرس أعمدة "اسم الكتاب" و "المؤلف" و "الرقم العالمي الموحد للكتاب" //
  في مصفوفة المتغير bookValues أدناه // 
  var TITLE_COLUMN = 0;
  var AUTHOR_COLUMN = 1;
  var ISBN_COLUMN = 2;

  الحصول على معلومات الكتب الموجودة في الورقة النشطة //
 وتوضع البيانات داخل المصفوفة //
  var dataRange = SpreadsheetApp.getActiveSpreadsheet()
    .getDataRange();
  var bookValues = dataRange.getValues();

  فحص كل صف من البيانات باستثناء رؤوس الصفوف //
  إذا كان رقم ISBN موجودًا وكان اسم الكتاب أو المؤلف مفقودًا //
  فاستخدم التابع (fetchBookData_ (isbn //
  لاسترداد البيانات المفقودة من Open Library API //
  ثم املأ عمود "اسم الكتاب" أو "المؤلف" المفقودين ببياناتهم عند العثور عليهم //
  for(var row = 1; row < bookValues.length; row++){   
    var isbn = bookValues[row][ISBN_COLUMN];
    var title = bookValues[row][TITLE_COLUMN];
    var author = bookValues[row][AUTHOR_COLUMN];

    if(isbn != "" && (title === "" || author === "") ){
      الاتصال فقط بواجهة برمجة التطبيقات إذا كان لديك رقم ISBN //
      وكان اسم الكتاب أو المؤلف مفقودًا //
      var bookData = fetchBookData_(isbn);

      في بعض الأحيان لا تقوم واجهة برمجة التطبيقات بإرجاع المعلومات المطلوبة //
     في هذه الحالة لا تحاول تحديث الصف //
      if (!bookData || !bookData.details) {
        continue;
      }

      قد لا تُرجع واجهة برمجة التطبيقات عنوانًا //
      لذا قم بملئها فقط إذا كانت الاستجابة تحتوي على عنوان //
     وإذا كان عمود "اسم الكتاب" فارغًا في الورقة //
      if(title === "" && bookData.details.title){
        bookValues[row][TITLE_COLUMN] = bookData.details.title; 
      }

      قد لا تُرجع واجهة برمجة التطبيقات اسم المؤلف //
      لذا قم بملئها فقط إذا كانت الاستجابة تحتوي على اسم المؤلف //
      وإذا كان عمود "المؤلف" فارغًا في الورقة //
      if(author === "" && bookData.details.authors
          && bookData.details.authors[0].name){
        bookValues[row][AUTHOR_COLUMN] =
          bookData.details.authors[0].name; 
      }
    }
  }

  أدخل قيم بيانات الكتاب المحدثة في جدول البيانات //
  dataRange.setValues(bookValues);
}

احفظ مشروع النص البرمجي الخاص بك.

مراجعة الشيفرة البرمجية

تنقسم هذه الشيفرة البرمجية إلى ثلاثة أقسام:

1. قراءة معلومات الكتاب الموجودة

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

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

اقتباس

تنويه: يختلف الترتيب في هذه الدالة عن الترتيب في دالة ()splitAtFirstComma ودالة ()splitAtLastBy، ففيهما تفحص الشيفرة البرمجية فقط الخلايا النشطة، أما هذه الدالة تفحص الورقة بأكملها باستخدام التابع ()Spreadsheet.getDataRange.

2. إحضار المعلومات المفقودة

تمر حلقة التكرار For في كل صف بالمتغير bookValues للعثور على العناوين أو المؤلفين المفقودة، وذلك لتقليل عدد مرات استدعاء الواجهة API لتحسين كفاءة الشيفرة البرمجية، فلا يستدعى الـ API إلا إذا كان ما يلي صحيحًا:

1. أن تحتوي الخلية بالعمود "الرقم العالمي الموحد للكتاب" على قيمة.
2. أن تكون الخلية بعمود "اسم الكتاب" أو عمود "المؤلف" فارغة.

فإذا تحقق الشرطان فإن الشيفرة البرمجية تستدعي واجهة التطبيقات البرمجية API باستخدام الدالة ()_fetchBookData وتُخزن النتيجة في المتغير bookData ليصبح لديك المعلومات المفقودة التي تريد إدراجها في ورقة جدول البيانات.

المهمة الوحيدة المتبقية هي إضافة المعلومات بالمتغير bookData في جدول البيانات الخاص بك، ومع ذلك قد يواجهك سوء حظ بعدم احتواء Open Library API على المعلومات التي تطلبها، أو قد تواجه أحيانًا مشكلة أخرى تمنعها من توفير تلك المعلومات، فإذا افترضت أن كل طلب تقدمه لواجهة برمجة التطبيقات سينجح، فلن تكون شيفرتك البرمجية قوية بما يكفي للتعامل مع الأخطاء غير المتوقعة.

وللتأكد من أن الشيفرات البرمجية الخاصة بك يمكنها معالجة أخطاء الـ API يجب أن تتحقق الشيفرة البرمجية من أن استجابة الـ API صالحة قبل محاولة استخدامها، فإنها تُجري فحصًا بسيطًا للتحقق من وجود bookData و bookData.details قبل محاولة القراءة منها، إذا كان أي منهما مفقودًا فهذا يعني أن واجهة برمجة التطبيقات لا تحتوي على البيانات التي تريدها، وفي هذه الحالة يخبر الأمر continue الشيفرة البرمجية بتخطي هذا الصف من جدول البيانات.

نعم قد لا تتمكن من ملء الخلايا الشاغرة، ولكن على الأقل لن يتعطل النص البرمجي الخاص بك.

3. إعادة كتابة المعلومات المحدثة في الورقة

يحتوي الجزء الأخير من الشيفرة البرمجية على فحوصات مماثلة للتحقق من أن واجهة برمجة التطبيقات (API) تعرض العنوان ومعلومات المؤلف، فتعمل الشيفرة البرمجية على تحديث مصفوفة bookValues فقط إذا كانت الخلية بعمود "اسم الكتاب" وعمود "المؤلف" فارغة، وكانت واجهة برمجة التطبيقات API تُرجع قيمة يمكنك وضعها هناك.

تخرج جملة التكرار For بعد فحص جميع الصفوف في ورقة جدول البيانات، والخطوة الأخيرة هي إعادة كتابة مصفوفة bookValues المحدّثة إلى جدول البيانات باستخدام التابع ()Range.setValues.

النتائج

يمكنك الآن رؤية تأثيرات الدالة ()fillInTheBlanksوهي تعمل إذ ستمكنك من إكمال تنظيم بيانات الكتب الخاصة بك، فقط اذهب إلى القائمة المخصصة "قائمة الكتب" واختر منها القائمة الفرعية "ملء الخلايا الفارغة بالعنوان والمؤلف" ومن المفترض أن تكون النتيجة لديك كما في الصورة التالية:

خاتمة

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

وفي المقال القادم سوف نتعمق أكثر في كيفية تنسيق البيانات داخل جدول بيانات.

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

اقرأ أيضًا

• أساسيات برمجة التطبيقات Apps Script باستخدام جداول بيانات جوجل
• التعامل مع جداول البيانات والأوراق والنطاقات من خلال Apps Script
• العمل مع البيانات في جداول بيانات جوجل من خلال Apps Script