使用字段掩码

字段掩码是一种供 API 调用方列出请求应返回或更新的字段的方式。使用 FieldMask 可让 API 避免不必要的工作并提高性能。在 Google 幻灯片 API 中，读取和更新方法都使用字段掩码。

如需比较不使用 字段掩码与使用字段掩码时响应正文中返回的内容，请参阅使用部分 资源。

使用字段掩码进行读取

演示文稿可能很大，而且您通常不需要读取请求返回的 presentations 资源的每个部分。您可以使用 fields 网址参数来限制幻灯片 API 响应中返回的内容。为了获得最佳 性能，请仅在回复中明确列出您 需要的字段。

fields 参数的格式与 FieldMask 的 JSON 编码相同。 简而言之，多个不同的字段以逗号分隔，子字段以英文句点分隔。字段名称可以采用 camelCase 或 separated_by_underscores 格式。为方便起见，同一类型的多个子字段可以列在圆括号内。

以下 presentations.get 方法请求示例使用 slides.pageElements(objectId,size,transform)字段掩码，仅提取演示文稿中所有幻灯片上 pageElement 对象 的对象 ID、 Size和 转换 ：

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

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

{
  "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"
          }
        }
     ]
    }
  ]
}

使用字段掩码进行更新

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

您还可以通过不在更新后的消息中指定字段，但将该字段添加到掩码中来取消设置字段。这会清除该字段之前拥有的任何值。

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

以下示例使用 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"
      }
    }
  ]
}