REST Resource: forms

资源：表单

Google 表单文档。表单是在云端硬盘中创建，删除表单或更改其访问权限保护是通过 Drive API 完成的。

JSON 表示法 
{
  "formId": string,
  "info": {
    object (Info)
  },
  "settings": {
    object (FormSettings)
  },
  "items": [
    {
      object (Item)
    }
  ],
  "revisionId": string,
  "responderUri": string,
  "linkedSheetId": string
}
字段
formId

string

仅限输出。表单 ID。
info

object (Info)

必需。表单的标题和说明。
settings

object (FormSettings)

表单的设置。必须使用 UpdateSettingsRequest 进行更新；在 forms.create 和 UpdateFormInfoRequest 期间，系统会忽略该属性。
items[]

object (Item)

必需。表单项的列表，可包括章节标题、问题、嵌入式媒体等。
revisionId

string

仅限输出。表单的修订版本 ID。在更新请求的 WriteControl 中使用，用于标识更改所基于的修订版本。

修订版本 ID 的格式可能会随时间而变化，因此应视为不透明。返回的修订版本 ID 只能保证在返回后的 24 小时内有效，并且不能跨用户共享。如果在两次调用之间未更改修订版本 ID，则表单未更改。相反，ID 发生变化（对于同一表单和用户）通常表示表单已更新；但是，ID 发生变化的也可能是内部因素，如 ID 格式更改。
responderUri

string

仅限输出。要与回复者共享的表单 URI。系统会打开一个页面，在该页面中，用户可以提交回复，但无法修改问题。
linkedSheetId

string

仅限输出。所关联 Google 表格的 ID，该表格用于累积此表单的回答（如果存在此类表格）。

信息

表单的常规信息。

JSON 表示法 
{
  "title": string,
  "documentTitle": string,
  "description": string
}
字段
title

string

必需。向回复者显示的表单标题。
documentTitle

string

仅限输出。可在云端硬盘中显示的文档的标题。如果 Info.title 为空，则 documentTitle 可能会显示在 Google 表单界面中的相应位置，并且对回复者可见。documentTitle 可以在创建时设置，但无法通过 batchUpdate 请求修改。如果您需要以程序化方式更新 documentTitle，请使用 Google Drive API。
description

string

表单的说明。

FormSettings

表单的设置。

JSON 表示法 
{
  "quizSettings": {
    object (QuizSettings)
  }
}
字段
quizSettings

object (QuizSettings)

与测验表单和评分相关的设置。

QuizSettings

与测验表单和评分相关的设置。必须使用 UpdateSettingsRequest 更新这些设置。

JSON 表示法 
{
  "isQuiz": boolean
}
字段
isQuiz

boolean

此表单是否为测验。如果值为 true，则会根据问题 Grading 为回复评分。如果此政策设为 false，系统会删除所有问题 Grading。

项

表单的单个项。kind 定义其所属的种类。

JSON 表示法 
{
  "itemId": string,
  "title": string,
  "description": string,

  // Union field kind can be only one of the following:
  "questionItem": {
    object (QuestionItem)
  },
  "questionGroupItem": {
    object (QuestionGroupItem)
  },
  "pageBreakItem": {
    object (PageBreakItem)
  },
  "textItem": {
    object (TextItem)
  },
  "imageItem": {
    object (ImageItem)
  },
  "videoItem": {
    object (VideoItem)
  }
  // End of list of possible types for union field kind.
}
字段
itemId

string

商品 ID。

创建时，可以提供此 ID，但不得在表单中使用该 ID。如果未提供，系统会分配新 ID。
title

string

商品的标题。
description

string

商品的说明。
联合字段 kind。必需。此项的种类。kind 只能是下列其中一项：
questionItem

object (QuestionItem)

向用户提出问题。
questionGroupItem

object (QuestionGroupItem)

通过一条主要提示向用户提出一个或多个问题。
pageBreakItem

object (PageBreakItem)

开始包含标题的新页面。
textItem

object (TextItem)

在页面上显示标题和说明。
imageItem

object (ImageItem)

在页面上显示一张图片。
videoItem

object (VideoItem)

在页面上显示视频。

QuestionItem

包含单个问题的表单项。

JSON 表示法 
{
  "question": {
    object (Question)
  },
  "image": {
    object (Image)
  }
}
字段
question

object (Question)

必需。显示的问题。
image

object (Image)

问题中显示的图片。

问题

有任何问题。具体类型的问题是通过其 kind 已知的。

JSON 表示法 
{
  "questionId": string,
  "required": boolean,
  "grading": {
    object (Grading)
  },

  // Union field kind can be only one of the following:
  "choiceQuestion": {
    object (ChoiceQuestion)
  },
  "textQuestion": {
    object (TextQuestion)
  },
  "scaleQuestion": {
    object (ScaleQuestion)
  },
  "dateQuestion": {
    object (DateQuestion)
  },
  "timeQuestion": {
    object (TimeQuestion)
  },
  "fileUploadQuestion": {
    object (FileUploadQuestion)
  },
  "rowQuestion": {
    object (RowQuestion)
  }
  // End of list of possible types for union field kind.
}
字段
questionId

string

只读。问题 ID。

创建时，可以提供此 ID，但不得在表单中使用该 ID。如果未提供，系统会分配新 ID。
required

boolean

是否必须回答问题，受访者才能提交回复。
grading

object (Grading)

题目的评分设置。
联合字段 kind。必需。向受访者提供的问题类型。kind 只能是下列其中一项：
choiceQuestion

object (ChoiceQuestion)

回复者可以从一组预定义的选项中进行选择。
textQuestion

object (TextQuestion)

回复者可以输入自由文本回复。
scaleQuestion

object (ScaleQuestion)

回复者可以选择一个数字范围。
dateQuestion

object (DateQuestion)

回复者可以输入日期。
timeQuestion

object (TimeQuestion)

回复者可以输入时间。
fileUploadQuestion

object (FileUploadQuestion)

回复者可以上传一个或多个文件。
rowQuestion

object (RowQuestion)

QuestionGroupItem 的行。

ChoiceQuestion

单选题/多选题/下拉列表问题。

JSON 表示法 
{
  "type": enum (ChoiceType),
  "options": [
    {
      object (Option)
    }
  ],
  "shuffle": boolean
}
字段
type

enum (ChoiceType)

必需。选择问题的类型。
options[]

object (Option)

必需。受访者必须选择的选项列表。
shuffle

boolean

是否针对测验的不同实例按随机顺序显示选项。这通常用于防止受访者在看其他受访者的屏幕时作弊，或者为了解决调查问卷中的偏见，因为始终将相同的选项放在最前面或最前面。

ChoiceType

所选类型。

枚举
CHOICE_TYPE_UNSPECIFIED 默认值。未使用。
RADIO 单选按钮：所有选项都会向用户显示，但用户只能选择其中一个。
CHECKBOX 复选框：所有选项都会向用户显示，用户可以选择其中任意多个选项。
DROP_DOWN 下拉菜单：选项只会按需向用户显示，否则只会显示当前选项。只能选择一个选项。

选项

“选择”问题的选项。

JSON 表示法 
{
  "value": string,
  "image": {
    object (Image)
  },
  "isOther": boolean,

  // Union field go_to_section can be only one of the following:
  "goToAction": enum (GoToAction),
  "goToSectionId": string
  // End of list of possible types for union field go_to_section.
}
字段
value

string

必需。向用户显示的选项。
image

object (Image)

将图片显示为选项。
isOther

boolean

选项是否为“其他”。目前仅适用于 RADIO 和 CHECKBOX 选项类型，但不允许在 QuestionGroupItem 中使用。
联合字段 go_to_section。选择此选项后要转到哪个部分。目前仅适用于 RADIO 和 SELECT 选项类型，但不允许在 QuestionGroupItem 中使用。go_to_section 只能是下列其中一项：
goToAction

enum (GoToAction)

版块导航类型。
goToSectionId

string

要转到的章节标题的项目 ID。

GoToAction

部分导航的常量。

枚举
GO_TO_ACTION_UNSPECIFIED 默认值。未使用。
NEXT_SECTION 前往下一部分。
RESTART_FORM 返回表单的开头。
SUBMIT_FORM 立即提交表单。

映像

表示图像的数据。

JSON 表示法 
{
  "contentUri": string,
  "altText": string,
  "properties": {
    object (MediaProperties)
  },

  // Union field image_source can be only one of the following:
  "sourceUri": string
  // End of list of possible types for union field image_source.
}
字段
contentUri

string

仅限输出。可供下载图片的 URI；此字段仅在有限的时间内有效。
altText

string

用户将鼠标悬停在其上并由屏幕阅读器读出的图片说明。
properties

object (MediaProperties)

图片的属性。
联合字段 image_source。图片来源的类型。创建新图片时，必须设置一个图片来源字段。image_source 只能是下列其中一项：
sourceUri

string

仅限输入。源 URI 是用于插入图片的 URI。提取源 URI 时可以为空。

MediaProperties

媒体的属性。

JSON 表示法 
{
  "alignment": enum (Alignment),
  "width": integer
}
字段
alignment

enum (Alignment)

媒体的位置。
width

integer

媒体的宽度（以像素为单位）。在显示媒体时，系统会将其调整为此值或所显示表单的宽度中的较小者。媒体的原始宽高比会保留下来。如果在向表单添加媒体时未指定宽度，则会将其设为媒体来源的宽度。宽度必须介于 0 到 740 之间（含 0 和 740）。只有在更新媒体来源时，才允许将宽度设置为 0 或未指定。

对齐

页面上的对齐方式。

枚举
ALIGNMENT_UNSPECIFIED 默认值。未使用。
LEFT 左对齐。
RIGHT 右对齐。
CENTER 中心位置。

TextQuestion

基于文字的问题。

JSON 表示法 
{
  "paragraph": boolean
}
字段
paragraph

boolean

问题是否为段落问题。如果不是，则问题为简短的文字问题。

ScaleQuestion

量表问题。用户可以从一系列数值中进行选择。

JSON 表示法 
{
  "low": integer,
  "high": integer,
  "lowLabel": string,
  "highLabel": string
}
字段
low

integer

必需。量表的可能最低值。
high

integer

必需。可能的最高比例值。
lowLabel

string

要显示的标签，用于描述刻度上最低点。
highLabel

string

要显示的标签，用于描述刻度上最高点。

DateQuestion

日期问题。日期问题默认仅显示月 + 天。

JSON 表示法 
{
  "includeTime": boolean,
  "includeYear": boolean
}
字段
includeTime

boolean

是否在问题中包含时间。
includeYear

boolean

问题中是否包含年份。

TimeQuestion

时间问题。

JSON 表示法 
{
  "duration": boolean
}
字段
duration

boolean

如果题目是关于已过去的时间的，则为 true。否则，将与一天中的时段差不多。

FileUploadQuestion

“文件上传”问题。该 API 目前不支持创建文件上传问题。

JSON 表示法 
{
  "folderId": string,
  "types": [
    enum (FileType)
  ],
  "maxFiles": integer,
  "maxFileSize": string
}
字段
folderId

string

必需。存储上传文件的云端硬盘文件夹的 ID。
types[]

enum (FileType)

此问题接受的文件类型。
maxFiles

integer

在一次回复中可以针对此问题上传的文件数上限。
maxFileSize

string (int64 format)

上传到此问题的任何单个文件允许的字节数上限。

FileType

可上传到“文件上传”问题的文件类型。

枚举
FILE_TYPE_UNSPECIFIED 默认值。未使用。
ANY 无类型限制。
DOCUMENT Google 文档。
PRESENTATION Google 幻灯片演示文稿。
SPREADSHEET Google 表格电子表格。
DRAWING 绘图。
PDF PDF。
IMAGE 图片。
VIDEO 视频。
AUDIO 音频文件。

RowQuestion

问题组中的问题的配置。

JSON 表示法 
{
  "title": string
}
字段
title

string

必需。QuestionGroupItem 中单个行的标题。

评分

为单个问题评分

JSON 表示法 
{
  "pointValue": integer,
  "correctAnswers": {
    object (CorrectAnswers)
  },
  "whenRight": {
    object (Feedback)
  },
  "whenWrong": {
    object (Feedback)
  },
  "generalFeedback": {
    object (Feedback)
  }
}
字段
pointValue

integer

必需。每个回复者都自动获得正确答案的最高点数。此值不能为负数。
correctAnswers

object (CorrectAnswers)

必需。问题的答案。系统会根据此字段自动对回复评分。
whenRight

object (Feedback)

系统为正确回答而显示的反馈。只能为提供了正确答案的选择题设置此反馈。
whenWrong

object (Feedback)

针对错误回答显示的反馈。只能为提供了正确答案的选择题设置此反馈。
generalFeedback

object (Feedback)

针对所有回答显示的反馈。这种方式通常用于简答题，如果测验所有者想要在回复者尚未正式对回答进行评分之前，快速了解他们是否正确回答了问题。无法为自动评分的选择题设置一般反馈。

CorrectAnswers

问题的答案键。

JSON 表示法 
{
  "answers": [
    {
      object (CorrectAnswer)
    }
  ]
}
字段
answers[]

object (CorrectAnswer)

正确答案列表。系统会根据这些答案自动为测验回复评分。对于单值问题，只要某个回复与此列表中的任何值匹配，系统就会将其标记为“正确”（换言之，可能会有多个正确答案）。对于多值 (CHECKBOX) 问题，如果一个回复与此列表中的值完全相同，系统就会将其标记为“正确”。

CorrectAnswer

一个问题的唯一正确答案。对于多值 (CHECKBOX) 问题，可能需要多个 CorrectAnswer 来表示一个正确的答案选项。

JSON 表示法 
{
  "value": string
}
字段
value

string

必需。正确答案值。如需详细了解如何设置各种值类型的格式，请参阅 TextAnswer.value 的文档。

QuestionGroupItem

定义由组合到一起的多个问题构成的问题。

JSON 表示法 
{
  "questions": [
    {
      object (Question)
    }
  ],
  "image": {
    object (Image)
  },

  // Union field kind can be only one of the following:
  "grid": {
    object (Grid)
  }
  // End of list of possible types for union field kind.
}
字段
questions[]

object (Question)

必需。属于此问题组的问题列表。一个题目只能属于一个组。群组的kind可能会影响允许的问题类型。
image

object (Image)

问题组中特定问题上方显示的图片。
联合字段 kind。必需。问题组的类型，决定允许的问题类型及其显示方式。kind 只能是下列其中一项：
grid

object (Grid)

问题组以网格形式，包含多个选择题各行。设置 grid 后，组中的所有问题都必须是 row 种类。

网格

选项网格（单选按钮或复选框），其中每一行构成一个单独的问题。每行都包含相同的选项，这些选项以列的形式显示。

JSON 表示法 
{
  "columns": {
    object (ChoiceQuestion)
  },
  "shuffleQuestions": boolean
}
字段
columns

object (ChoiceQuestion)

必需。网格中每个问题共享的选项。换言之，列的值。只允许选择 CHECK_BOX 和 RADIO。
shuffleQuestions

boolean

如果值为 true，则问题会随机排序。换言之，这些行以不同的顺序显示给每个受访者。

PageBreakItem

分页符。该项的标题和说明会显示在新页面的顶部。

TextItem

文本项。

ImageItem

包含图片的项。

JSON 表示法 
{
  "image": {
    object (Image)
  }
}
字段
image

object (Image)

必需。商品中显示的图片。

VideoItem

包含视频的项。

JSON 表示法 
{
  "video": {
    object (Video)
  },
  "caption": string
}
字段
video

object (Video)

必需。作品中显示的视频。
caption

string

显示在视频下方的文字。

视频

表示视频的数据。

JSON 表示法 
{
  "youtubeUri": string,
  "properties": {
    object (MediaProperties)
  }
}
字段
youtubeUri

string

必需。YouTube URI。
properties

object (MediaProperties)

视频的属性。

方法

batchUpdate

 使用批量更新更改表单。

create

 使用请求中提供的表单消息中提供的标题创建新表单。

get

 获取表单。