نظرة عامة

واجهة برمجة تطبيقات "نماذج 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"
              }
            ]
          }
        }
      }
    }
  ]
}

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