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

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

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

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

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

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

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

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

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. انقر على حفظ المشروع وتصحيح أي أخطاء في الصيغة إذا لزم الأمر. من المفترض أن يتمكّن مشروعك الآن من طلب بيانات من 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 بنجاح، يمكنك الرجوع إلى المستندات المرجعية وتجربة إجراء طلبات أخرى من واجهة برمجة التطبيقات.