نظرة عامة

واجهة برمجة تطبيقات "نماذج 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. 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"
              }
            ]
          }
        }
      }
    }
  ],
  "publishSettings" : {
    "isPublished": true,
    "isAcceptingResponses": true
  }
}

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