使用字段掩码

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

使用字段掩码进行读取

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

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

以下 presentations.get 请求示例使用 slides.pageElements(objectId,size,transform) 仅提取对象 ID, Sizetransform (针对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 请求会忽略字段掩码中未指定的任何字段, 保留其当前值

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

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

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