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.createUpdateFormInfoRequest 期间,系统会将其忽略。

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

选项是否为“other”。目前仅适用于 RADIOCHECKBOX 选项类型,但不允许在 QuestionGroupItem 中使用。

联合字段 go_to_section。选择此选项后要转到的版块。目前仅适用于 RADIOSELECT 选项类型,但不适用于 QuestionGroupItemgo_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,您可以从中下载图像;此 URI 仅在有限的时间内有效。

altText

string

图片说明,将鼠标悬停在图片上方时显示,供屏幕阅读器读取。

properties

object (MediaProperties)

图片的属性。

联合字段 image_source。图片来源的类型。创建新图片时,必须设置 1 个图片来源字段。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_BOXRADIO

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

获取表单。