使用欄位遮罩

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 要變更哪些欄位。更新要求會忽略欄位遮罩中未指定的任何欄位，並保留這些欄位的目前值。

您也可以在更新的訊息中不指定欄位，但將欄位新增至遮罩，即可取消設定欄位。這會清除欄位先前的值。

更新欄位遮罩的語法與讀取欄位遮罩相同。

* 的欄位遮罩會視為萬用字元，是指定訊息中每個欄位的簡寫。如果日後更新 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
        },
      }
    }
  ],
}