欄位遮罩是 API 呼叫端用來列出要求應傳回或更新的欄位。使用 FieldMask 可讓 API 避免不必要的工作，並提升效能。欄位遮罩可用於 Google 文件 API 中的讀取和更新方法。
使用欄位遮罩讀取
文件可能很大，而且您通常不需要讀取要求傳回的 Document 資源的每個部分。您可以使用 fields 網址參數來限制 Docs API 回應中傳回的內容。為獲得最佳效能，請在回覆中明確列出您需要的欄位。
fields 參數的格式與 FieldMask 的 JSON 編碼相同。簡單來說，多個不同的欄位以半形逗號分隔，子欄位則以點號分隔。您可以使用 大寫字母與小寫字母混合或 以底線分隔的方式指定欄位名稱。為了方便起見，您可以將同類型中的多個子欄位列在括號內。
以下 documents.get 要求範例使用 title,tabs(documentTab(body.content(paragraph))),revisionId 的欄位遮罩來擷取文件的 title、Body 物件的 Paragraph (從所有分頁)，以及文件內的 revisionId：
GET https://docs.googleapis.com/v1/documents/documentId?fields=title,tabs(documentTab(body.content(paragraph))),revisionId
這個方法呼叫的回應為 Document 物件，其中包含欄位遮罩中要求的元件：
{
"title": "TITLE",
"revisionId": "REVISION_ID",
"tabs": [
{
"documentTab": {
"body": {
"content": [
{},
{
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 59,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
}
}
}
]
}使用欄位遮罩更新
有時您只需要更新物件中的特定欄位，而其他欄位則保持不變。更新 documents.batchUpdate 作業用途欄位遮罩中的要求，通知 API 哪些欄位即將變更。更新要求會忽略欄位遮罩中未指定的任何欄位，並保留這些欄位目前的值。
您也可以在更新的訊息中不指定欄位，但將欄位新增至遮罩，藉此取消設定欄位。這麼做會清除欄位先前的任何值。
更新欄位遮罩的語法與讀取欄位遮罩的語法相同。
以下範例使用 UpdateTextStyleRequest，在 range 5 到 20 中，將文件中的「Google Docs API」字詞設定成粗體：
POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{
"title": "TITLE",
"revisionId": "REVISION_ID",
"suggestionsViewMode": "SUGGESTIONS_INLINE",
"documentId": "DOCUMENT_ID",
"tabs": [
{
"documentTab": {
"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
},
}
}
],
}