概览

Google 表单 API 是一个 RESTful 接口,可用于创建和修改表单和测验、检索表单回复和测验成绩、设置测验答案键和自动反馈,以及接收推送通知。此 API 最常见的用途包括以下任务:

  • 创建表单或测验
  • 更新表单或测验
  • 从表单或测验中检索回复
  • 读取表单内容和元数据
  • 设置和接收推送通知

以下是 Form API 中使用的常用术语列表:

形式

在云端硬盘中创建并存储的 Google 表单文档。每种形式都由一个 Form 资源表示,并且具有唯一的 formId 值,其中包含字母、数字、连字符或下划线。您可以在 Google 表单网址中找到表单 ID:

https://docs.google.com/forms/d/FORM_ID/edit

测验

一种特定类型的 Google 表单文档,可用于根据答案表对表单回复进行评分。要创建测验,只能使用 batchUpdate() 方法将现有表单上的 isQuiz 设置更新为 true

评分
问题的分数、答案键和反馈,在 isQuiztrue 时应用。由 Grading 资源表示。
反馈
在回复测验中的问题时对最终用户的响应,由 Feedback 资源表示。
资源项

表单中的单个元素,由 Item 资源表示。Item 是重复元素,可以包含小节、问题组、问题、文本、图片或视频。

问题

表单上的单个问题,由 Question 资源表示。

问题组

共享同一组可能答案的一组问题(例如,评分为 1 到 5 的网格)。由 QuestionGroupItem 资源表示。

Section

利用部分,可以将表单拆分为多个页面并添加条件逻辑(例如,根据用户的回答仅显示某些问题)。区段对应 PageBreakItem 资源。

接听

最终用户对问题的回答,由 Answer 资源表示。包括成绩信息(如果存在)、元数据和答案内容。

答案

最终用户提交的表单,由 FormResponse 资源表示。

Watch 设备

一个触发器,用于跟踪对表单架构更改(例如问题修改)或表单回复提交的更改,并在发生更改时发送推送通知。由 Watch 资源表示。

表单结构

管理表单和测验时,由于许多表单对象可以通过多种方式相互嵌套,因此了解如何指定不同字段可能非常复杂。如需查看表单的直观表示形式与字段的对应关系,我们建议您使用界面创建一些应用可能生成的表单示例。然后,使用 forms.get() 方法检索相应的 JSON,以便进行比较。例如,此示例测验与以下 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 API 进行开发(包括处理身份验证和授权),请参阅Workspace 开发者入门
  • 如需了解如何配置和运行简单的 Form API 应用,请参阅快速入门概览