نظرة عامة

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

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

في ما يلي قائمة بالمصطلحات الشائعة المستخدَمة في 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"
              }
            ]
          }
        }
      }
    }
  ]
}

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