نظرة عامة

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

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

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

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

• لمزيد من المعلومات عن التطوير باستخدام واجهات برمجة التطبيقات في Google Workspace، بما في ذلك التعامل مع المصادقة والترخيص، راجِع مقالة البدء كمطوِّر Workspace.
• للتعرُّف على كيفية ضبط وتشغيل تطبيق بسيط من واجهة برمجة التطبيقات في "نماذج Google"، اطّلِع على نظرة عامة على خطوات البدء السريع.