نظرة عامة

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

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

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

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

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