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

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

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

في ما يلي شرح سريع لهذه الخطوات.

إنشاء مشروع جديد في "برمجة تطبيقات Google" وإعداده

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

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

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

لإنشاء رمز مميّز لنظام OAuth بنطاق محدّد بشكل صحيح في "برمجة تطبيقات Google"، عليك ضبط النطاقات المطلوبة في ملف بيان المشروع.

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!');
     const formId = '<YOUR_FORM_ID>';
   
     // Get OAuth Token
    const OAuthToken = ScriptApp.getOAuthToken();
    console.log('OAuth token is: ' + OAuthToken);
    const formsAPIUrl = 'https://forms.googleapis.com/v1/forms/' + formId + '/' + 'responses';
    console.log('formsAPIUrl is: ' + formsAPIUrl);
    const options = {
       'headers': {
         Authorization: 'Bearer ' + OAuthToken,
         Accept: 'application/json'
       },
       'method': 'get'
     };  
   const 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، يمكنك الرجوع إلى المستندات المرجعية وتجربة إجراء طلبات أخرى من واجهة برمجة التطبيقات.