フィールド マスクを使用すると、API 呼び出し元がリクエストで返すまたは更新するフィールドを一覧表示できます。FieldMask を使用すると、API で不要な処理を回避でき、パフォーマンスが向上します。フィールド マスクは、Google Sheets API の read メソッドと update メソッドの両方で使用されます。
フィールド マスクを使用して読み取る
プレゼンテーションはサイズが大きい場合があり、読み取りリクエストによって返される Presentation
リソースのすべての部分が必要になるとは限りません。fields
URL パラメータを使用すると、Slides API レスポンスで返される内容を制限できます。最適なパフォーマンスを得るには、返信に必要なフィールドのみを明示的に列挙します。
fields パラメータの形式は、FieldMask の JSON エンコードと同じです。つまり、複数の異なるフィールドはカンマで区切り、サブフィールドはドットで区切ります。フィールド名は、camelCase または separate_by_underscores で指定できます。便宜上、同じ型の複数のサブフィールドをかっこ内に記載できます。
次の presentations.get
リクエストの例では、slides.pageElements(objectId,size,transform)
のフィールド マスクを使用して、プレゼンテーション内のすべてのスライドのオブジェクト ID Size
と 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 に伝えます。更新リクエストでは、フィールド マスクで指定されていないフィールドは無視され、現在の値がそのまま残ります。
更新されたメッセージでフィールドを指定せず、フィールドをマスクに追加して、フィールドの設定を解除することもできます。これにより、そのフィールドに以前設定されていた値がクリアされます。
更新フィールド マスクの構文は、読み取りフィールド マスクと同じです。
次の例では、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"
}
}
]
}