欄位遮罩是 API 呼叫端列出要求應傳回或更新欄位的方法。使用 FieldMask 可讓 API 避免不必要的工作並提升效能。在 Google Document API 中,讀取和更新方法皆使用欄位遮罩。
使用欄位遮罩讀取
文件可能較大,且通常不需要讀取要求傳回的 Document
資源中的所有部分。您可以使用 fields
網址參數限制 Document API 回應傳回的內容。為獲得最佳效能,請在回覆中明確列出您需要的欄位。
欄位參數的格式與 FieldMask 的 JSON 編碼相同。簡單來說,多個不同欄位都以半形逗號分隔,子欄位則以半形句號分隔。欄位名稱可使用 camelCase 或 split_by_underscores 指定。為了方便起見,您可以在括號內列出相同類型的多個子欄位。
以下 documents.get
要求範例使用 title,body.content(paragraph),revisionId
的欄位遮罩擷取文件的 title
、Body
物件的 Paragraph
,以及文件中的文件 revisionId
:
GET https://docs.googleapis.com/v1/documents/documentId?fields=title,body.content(paragraph),revisionId
這個方法呼叫的回應是一個 Document
物件,其中包含欄位遮罩中要求的元件:
{ "title": ""TITLE
", "body": { "content": [ {}, { "paragraph": { "elements": [ { "startIndex": 1, "endIndex": 59, "textRun": { "content": ""CONTENT
", "textStyle": {} } } ], "paragraphStyle": { "namedStyleType": "NORMAL_TEXT", "direction": "LEFT_TO_RIGHT" } } } ] }, "revisionId": "REVISION_ID
" }
以欄位遮罩更新
有時候,您只需要更新物件的特定欄位,其他欄位則保持不變。更新 documents.batchUpdate
作業使用欄位遮罩內的要求,讓 API 知道哪些欄位要變更。更新要求會忽略未在欄位遮罩中指定的任何欄位,並保留這些欄位目前的值。
您也可以取消設定欄位,只要在更新後的訊息中未指定欄位,並將欄位新增至遮罩中即可。這樣做會清除欄位先前使用的任何值。
更新欄位遮罩的語法與讀取欄位遮罩相同。
以下範例使用 UpdateTextStyleRequest
,在 range
5 到 20 內將文件中的「Google Document API」字詞設為粗體:
POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{ "title": "TITLE
", "body": { "content": [ { "endIndex": 1, "sectionBreak": { "sectionStyle": { "columnSeparatorStyle": "NONE", "contentDirection": "LEFT_TO_RIGHT", "sectionType": "CONTINUOUS" } } }, { "startIndex": 1, "endIndex": 59, "paragraph": { "elements": [ { "startIndex": 1, "endIndex": 5, "textRun": { "content": "CONTENT
", "textStyle": {} } }, { "startIndex": 5, "endIndex": 20, "textRun": { "content": "CONTENT
", "textStyle": { "bold": true } } }, { "startIndex": 20, "endIndex": 59, "textRun": { "content": "CONTENT
", "textStyle": {} } } ], "paragraphStyle": { "namedStyleType": "NORMAL_TEXT", "direction": "LEFT_TO_RIGHT" } } } ] }, { ... // style details }, "revisionId": "REVISION_ID
", "suggestionsViewMode": "SUGGESTIONS_INLINE", "documentId": "DOCUMENT_ID
" }