إعداد مشروع برمجة التطبيقات

إنّ إعداد مشروع على Apps Script لطلب Google Forms API مباشرةً من خلال ملف REST هو عملية سهلة. على افتراض أنّك سبق لك إعداد مشروع على Google Cloud، اتّبِع الخطوات التالية:

1. أنشئ مشروعًا جديدًا في Apps Script.
2. غيِّر رقم مشروع Google Cloud المرتبط ليتطابق مع المشروع الذي فعّلته لواجهة برمجة التطبيقات Google Forms API.
3. عدِّل ملف البيان (appsscript.json) لإضافة نطاقات OAuth الضرورية.
4. أضِف رمز Apps Script لجلب رمز مميز لبروتوكول OAuth وإجراء طلب REST باستخدام الرمز المميّز.

في ما يلي نظرة سريعة على هذه الخطوات.

إنشاء مشروع جديد في Apps Script وضبطه

1. باستخدام رقم تعريف Google نفسه الذي أعددت به مشروعك على Google Cloud Platform، انتقِل إلى لوحة بيانات Apps Script، ثم انقر على مشروع جديد.
2. بعد فتح مشروعك، انقر على إعدادات المشروع.
3. ضَع علامة في مربّع الاختيار عرض ملف البيان "appsscript.json" في المحرّر.
4. في قسم مشروع Google Cloud Platform (GCP)، انقر على تغيير المشروع وأدخِل رقم مشروع GCP الذي أعددته لواجهة برمجة التطبيقات Forms API.

تم الآن ضبط مشروعك على Apps Script للوصول إلى Google Forms API. الخطوة التالية المطلوب اتّباعها هي إضافة نطاقات OAuth المناسبة.

إضافة نطاقات OAuth

لإنشاء رمز مميّز OAuth بنطاق مناسب في Apps Script، عليك ضبط النطاقات المطلوبة في ملف بيان المشروع.

1. في المحرِّر، افتح appsscript.json.

2. أضِف النطاقات إلى نص البيان.

   ملاحظة: لكل طريقة من طرق واجهة برمجة التطبيقات متطلبات خاصة بنطاق OAuth (مثال). ما عليك سوى تضمين النطاقات للطرق التي تستخدمها. على سبيل المثال، إذا كنت تخطّط فقط لاسترداد الردود على النماذج، ستحتاج إلى forms.responses.readonly فقط. يجب استخدام نطاق script.external_request للسماح لخدمة Apps Script بالاتصال بخدمة REST خارجية.

   {
     ...
   "oauthScopes": [
       "https://www.googleapis.com/auth/script.external_request",
       "https://www.googleapis.com/auth/drive",
       "https://www.googleapis.com/auth/drive.readonly",
       "https://www.googleapis.com/auth/forms.body",
       "https://www.googleapis.com/auth/forms.body.readonly",
       "https://www.googleapis.com/auth/forms.responses.readonly"
     ],
    ...
    }
   

3. انقر على حفظ المشروع وصحِّح أي أخطاء نحوية إذا لزم الأمر. من المفترض أن يتمكّن مشروعك الآن من طلب بيانات من واجهة برمجة التطبيقات Google Forms API من خلال طلب REST.

إضافة رمز "برمجة تطبيقات Google" لاستدعاء واجهة برمجة التطبيقات

قبل كتابة الرمز لاستدعاء نموذج، عليك تحديد نموذج تملكه يحتوي على ردود وتدوين رقم تعريف النموذج. يمكن العثور على معرّف النموذج في عنوان URL عند تعديل النموذج:

https://docs.google.com/forms/d/<FORM_ID>/edit

لطلب البيانات من واجهة برمجة التطبيقات، ستستخدم طلب UrlFetchApp في Apps Script.

1. افتح Code.gs وأضِف الرمز التالي:

   forms-api/snippets/retrieve_all_responses.gs

   العرض على GitHub
    function callFormsAPI() {
     console.log('Calling the Forms API!');
     var formId = '<YOUR_FORM_ID>';
   
     // Get OAuth Token
    var OAuthToken = ScriptApp.getOAuthToken();
    console.log('OAuth token is: ' + OAuthToken);
    var formsAPIUrl = 'https://forms.googleapis.com/v1/forms/' + formId + '/' + 'responses';
    console.log('formsAPIUrl is: ' + formsAPIUrl);
    var options = {
       'headers': {
         Authorization: 'Bearer ' + OAuthToken,
         Accept: 'application/json'
       },
       'method': 'get'
     };  
   var response = UrlFetchApp.fetch(formsAPIUrl, options);
    console.log('Response from forms.responses was: ' + response);
   }

2. استبدِل YOUR_FORM_ID بالقيمة التي دونتها سابقًا.

   مثلاً: var formId = 'tL5ygBC8zpbTnTp76JCZdIg80hA-cnpbTnTjnsewCKJH';

3. انقر على حفظ المشروع وعدِّل أي أخطاء نحوية إذا لزم الأمر.

اختبار الرمز

1. انقر على تشغيل.
2. فوِّض المشروع حسب الحاجة باستخدام معرّف Google نفسه كما في السابق.

بعد بدء عملية التنفيذ، من المفترض أن يظهر لك ردّ في سجلّ التنفيذ مشابهًا لردّ هذا:

Execution started
Calling the Forms API!
OAuth token is: ya29.a0ARrdaM8IMjtlv…
formsAPIUrl is: https://forms.googleapis.com/v1beta/forms/…/responses
Response from Forms.responses was: {
"responses": [
    {
      "responseId":"...",
      "createTime": "2021-03-25T01:23:58.146Z",
      "lastSubmittedTime": "2021-03-25T01:23:58.146607Z",
      "answers": {
        "1e9b0ead": {
          "questionId": "1e9b0ead",
          "textAnswers": {
            "answers": [
              {
                "value": "Red"
              }
            ]
          }
        },
        "773ed8f3": {
          "questionId": "773ed8f3",
          "textAnswers": {
            "answers": [
              {
                "value": "Tesla"
              }
            ]
          }
        }
      }
    }
  ]
}
Execution completed

الخطوات التالية

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