نظرة عامة

واجهة برمجة تطبيقات "نماذج Google" هي واجهة RESTful تتيح لك إنشاء النماذج والاختبارات وتعديلها، واسترداد الردود على النماذج ودرجات الاختبارات، وإعداد مفاتيح إجابات الاختبارات مع ملاحظات تلقائية، وتلقّي إشعارات فورية. تشمل الاستخدامات الأكثر شيوعًا لواجهة برمجة التطبيقات هذه المهام التالية:

  • إنشاء نموذج أو اختبار
  • تعديل نموذج أو اختبار
  • استرداد الردود من نموذج أو اختبار
  • قراءة محتوى النموذج والبيانات الوصفية
  • إعداد الإشعارات الفورية وتلقّيها

في ما يلي قائمة بالمصطلحات الشائعة المُستخدَمة في Forms API:

النموذج

مستند "نماذج Google" تم إنشاؤه وتخزينه في Drive يتم تمثيل كل نموذج بمورد Form ويحتوي على قيمة formId فريدة، تحتوي على أحرف أو أرقام أو واصلات أو شريط سفلي. يمكنك العثور على معرّف النموذج في عنوان URL لخدمة "نماذج Google":

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

اختبار

نوع معيّن من مستندات "نماذج Google" يتيح تقييم ردود النماذج استنادًا إلى مفتاح إجابة. لا يمكن إنشاء اختبار إلا باستخدام الطريقة batchUpdate() لتعديل إعدادات isQuiz في نموذج حالي إلى true.

وضع الدرجات
يتم تطبيق قيمة النقاط ومفتاح الإجابة والملاحظات على سؤال عندما تكون قيمة isQuiz هي true. يُمثّل ذلك المورد Grading.
الملاحظات
ردّ يُعطى للمستخدم النهائي عند الردّ على سؤال في اختبار، ويمثّله المرجع Feedback.
العنصر

تمثّل هذه السمة عنصرًا واحدًا في نموذج، ويتم تمثيله بمورد العنصر. Item هو عنصر متكرّر يمكن أن يحتوي على قسم أو مجموعة أسئلة أو سؤال أو نص أو صورة أو فيديو.

السؤال

سؤال واحد في النموذج، يمثّله المورد Question.

مجموعة الأسئلة

مجموعة من الأسئلة التي تشترك جميعها في نفس مجموعة الإجابات المحتملة (على سبيل المثال، شبكة من التقييمات من 1 إلى 5). يُرمز إليه بالمورد QuestionGroupItem.

Section

القسم هو طريقة لتقسيم نموذج إلى صفحات متعددة وإضافة منطق مشروط (مثل عرض أسئلة معيّنة فقط استنادًا إلى إجابة العميل). تتطابق الأقسام مع موارد PageBreakItem.

الإجابة

إجابة المستخدم النهائي عن سؤال، يتم تمثيلها بمورد Answer يتضمّن كلاً من معلومات الدرجة (إن توفّرت) والبيانات الوصفية و محتوى الإجابة.

الاستجابة

إرسال المستخدِم النهائي لنموذج، يمثّله المورد FormResponse.

المشاهدة

عامل تشغيل يتتبّع التغييرات في مخطّط النموذج (مثل التعديلات على الأسئلة) أو عمليات إرسال الردود على النموذج ويُرسِل إشعارًا فوريًا عند حدوث تغيير يُرمز إليه بالمورد Watch.

بنية النموذج

عند إدارة النماذج والاختبارات، قد يكون فهم كيفية تحديد حقول مختلفة معقدًا، نظرًا لأن العديد من كائنات النموذج يمكن دمجها داخل بعضها البعض بعدة طرق. لمعرفة كيفية ربط التمثيل المرئي للنموذج بالحقول، ننصحك باستخدام واجهة المستخدم لإنشاء بعض الأمثلة على النماذج التي قد ينشئها تطبيقك. بعد ذلك، يمكنك استرداد ملف JSON المقابل باستخدام الطريقة forms.get() حتى تتمكّن من إجراء المقارنة. على سبيل المثال، يتوافق مثال الاختبار هذا مع ملف JSON التالي:

{
  "formId": "FORM_ID",
  "info": {
    "title": "Famous Black Women",
    "description": "Please complete this quiz based off of this week's readings for class.",
    "documentTitle": "API Example Quiz"
  },
  "settings": {
    "quizSettings": {
      "isQuiz": true
    }
  },
  "revisionId": "00000021",
  "responderUri": "https://docs.google.com/forms/d/e/1FAIpQLSd0iBLPh4suZoGW938EU1WIxzObQv_jXto0nT2U8HH2KsI5dg/viewform",
  "items": [
    {
      "itemId": "5d9f9786",
      "imageItem": {
        "image": {
          "contentUri": "DIRECT_URL",
          "properties": {
            "alignment": "LEFT"
          }
        }
      }
    },
    {
      "itemId": "72b30353",
      "title": "Which African American woman authored \"I Know Why the Caged Bird Sings\"?",
      "questionItem": {
        "question": {
          "questionId": "25405d4e",
          "required": true,
          "grading": {
            "pointValue": 2,
            "correctAnswers": {
              "answers": [
                {
                  "value": "Maya Angelou"
                }
              ]
            }
          },
          "choiceQuestion": {
            "type": "RADIO",
            "options": [
              {
                "value": "Maya Angelou"
              },
              {
                "value": "bell hooks"
              },
              {
                "value": "Alice Walker"
              },
              {
                "value": "Roxane Gay"
              }
            ]
          }
        }
      }
    },
    {
      "itemId": "0a4859c8",
      "title": "Who was the first Dominican-American woman elected to state office?",
      "questionItem": {
        "question": {
          "questionId": "37fff47a",
          "grading": {
            "pointValue": 2,
            "correctAnswers": {
              "answers": [
                {
                  "value": "Grace Diaz"
                }
              ]
            }
          },
          "choiceQuestion": {
            "type": "RADIO",
            "options": [
              {
                "value": "Rosa Clemente"
              },
              {
                "value": "Grace Diaz"
              },
              {
                "value": "Juana Matias"
              },
              {
                "value": "Sabrina Matos"
              }
            ]
          }
        }
      }
    }
  ]
}

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