REST Resource: forms

資源:表單

Google 表單文件。表單是在雲端硬碟中建立,因此您必須透過 雲端硬碟 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 表單 UI 中,供作答者查看。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)
  },
  "ratingQuestion": {
    object (RatingQuestion)
  }
  // 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 的一列。

ratingQuestion

object (RatingQuestion)

受訪者可以從預先定義的一組圖示中選擇評分。

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

表示選項是否為「其他」。目前僅適用於 RADIOCHECKBOX 選項類型,但不允許在 QuestionGroupItem 中使用。

聯集欄位 go_to_section。選取這個選項後,系統會導向哪個部分。目前僅適用於 RADIOSELECT 選擇類型,但不允許在 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 時,來源 URI 可能會為空白。

MediaProperties

媒體的屬性。

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

enum (Alignment)

媒體的位置。

width

integer

媒體的寬度 (以像素為單位)。顯示媒體時,系統會將媒體縮放至較小值 (此值或顯示表單的寬度)。媒體會保留原始的長寬比。如果在媒體新增至表單時未指定寬度,系統會將寬度設為媒體來源的寬度。寬度必須介於 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 中單一資料列的標題。

RatingQuestion

評分問題。使用者可選擇多種圖示。

JSON 表示法
{
  "ratingScaleLevel": integer,
  "iconType": enum (RatingIconType)
}
欄位
ratingScaleLevel

integer

必要欄位。評分問題的評分等級。

iconType

enum (RatingIconType)

必要欄位。評分圖示類型。

RatingIconType

評分圖示的類型。

列舉
RATING_ICON_TYPE_UNSPECIFIED 預設值。未使用。
STAR 星號圖示。
HEART 心形圖示。
THUMB_UP 拇指向下圖示。

成績

評分單一問題

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

取得表單。