使用字段掩码

API 调用方可通过字段掩码列出请求应显示的字段 return 或更新。使用 FieldMask 可让 API 避免不必要的工作并提升性能。字段掩码 Google 幻灯片 API 中的 read 和 update 方法都使用该方法。

使用字段掩码进行读取

演示文稿可能很大，而且通常不需要 Presentation 读取请求返回的资源您可以限制在 使用 fields 网址参数实现幻灯片 API 响应。最佳 性能 仅明确列出您需要的字段 。

fields 参数的格式与 FieldMask 的 JSON 编码。 简单来说，多个不同字段用英文逗号分隔，而子字段则用 以英文句点分隔。字段名称可以采用 camelCase 或 separated_by_underscores 中。为方便起见，同一个字段的多个子字段 可以用括号列出。

以下 presentations.get 请求示例使用如下字段掩码： slides.pageElements(objectId,size,transform) 仅提取对象 ID， Size和 transform （针对pageElement） 对象：

GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)

对此方法调用的响应是一个 Presentation 对象 包含字段掩码中请求的组件：

{
  "slides": [
    {
      "pageElements": [
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311708,
            "translateY": 744575,
            "unit": "EMU"
          }
        },
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311700,
            "translateY": 2834125,
            "unit": "EMU"
          }
        }
     ]
    }
  ]
}

使用字段掩码进行更新

有时，您只需要更新对象中的某些字段，而保留 其他字段保持不变。在 presentations.batchUpdate 操作使用字段掩码来告知 API 正在更改哪些字段。通过 update 请求会忽略字段掩码中未指定的任何字段， 保留其当前值

您也可以取消设置某个字段，只需不在更新后的消息中指定该字段即可，但 将该字段添加到掩码。这会清除 。

更新字段掩码的语法与读取字段掩码的语法相同。

字段掩码 * 会被视为通配符 是用于指定消息中的每个字段的简写形式。通配符语法 如果将来更新 API，可能会产生不需要的结果，因为只读模式 字段和新添加的字段可能会导致错误。对于生产应用 始终在字段掩码中列出要更新的特定字段，并避免使用 * 通配符。

以下示例使用 UpdateShapePropertiesRequest 可将形状的颜色填充更改为 DARK1 主题颜色，并取消设置形状的 概述：

POST https://slides.googleapis.com/v1/presentations/presentationId:batchUpdate

{
  "requests": [
    {
      "updateShapeProperties": {
        "objectId": OBJECT_ID,
        "shapeProperties": {
          "shapeBackgroundFill": {
            "solidFill": {
              "color": {
                "themeColor": "DARK1"
              }
            }
          }
        },
        "fields": "shapeBackgroundFill.solidFill.color,outline"
      }
    }
  ]
}