API 调用方可通过字段掩码的方式列出请求应返回或更新的字段。使用 FieldMask 可使 API 避免执行不必要的工作，从而提升性能。Google 文档 API 中的 read 和更新方法都使用字段掩码。
使用字段掩码进行读取
文档可能很大，通常您不需要读取请求返回的 Document 资源的每个部分。您可以使用 fields 网址参数限制在 Docs API 响应中返回的内容。为获得最佳性能，请在回复中仅明确列出您需要的字段。
字段参数的格式与 FieldMask 的 JSON 编码 相同。简单地说，多个不同字段用逗号隔开，子字段用句点隔开。字段名称可以采用 camelCase 或 Separate_by_underscores 指定。为方便起见，可在括号中列出多个相同类型的子字段。
以下 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 文档 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
},
}
}
],
}