نظرة عامة

واجهة برمجة تطبيقات 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.
  • لمعرفة كيفية ضبط تطبيق بسيط لـ Forms API وتشغيله، يمكنك الاطّلاع على نظرة عامة على البدء السريع.