使用欄位遮罩

API 呼叫者可透過欄位遮罩列出要求應傳回或更新的欄位。使用 FieldMask 可讓 API 避免不必要的工作，進而提升效能。在 Google 文件 API 中，讀取和更新方法都會使用欄位遮罩。

使用欄位遮罩讀取

文件可能很大，而且通常您不需要讀取要求傳回的資源中Document的每個部分。您可以使用 fields 網址參數，限制在 Google 文件 API 回應中傳回的內容。為獲得最佳成效，請在回覆中明確列出您需要的欄位。

欄位參數的格式與 FieldMask 的 JSON 編碼相同。 簡單來說，多個不同欄位會以半形逗號分隔，子欄位則以半形句號分隔。欄位名稱可以指定為 camelCase 或以底線分隔。為方便起見，同一類型的多個子欄位可以列在括號內。

下列 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，將文件中的「Google Docs API」一詞在 range 5 到 20 之間設為粗體：

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
        },
      }
    }
  ],
}