フィールド マスクを使用すると、API 呼び出し元は、リクエストで返または更新する必要があるフィールドをリストできます。FieldMask を使用すると、API で不要な処理を回避でき、パフォーマンスが向上します。フィールド マスクは、Google Sheets API の読み取りメソッドと更新メソッドの両方で使用されます。
フィールド マスクを使用した読み取り
スプレッドシートはサイズが大きくなる場合があり、多くの場合、読み取りリクエストで返される Spreadsheet
リソースのすべての部分は必要ありません。fields
URL パラメータを使用すると、Sheets API のレスポンスで返される内容を制限できます。最適なパフォーマンスを得るには、応答で必要なフィールドのみを明示的に列挙します。
fields パラメータの形式は FieldMask の JSON エンコードと同じです。簡単に言うと、複数の異なるフィールドはカンマ区切りで、サブフィールドはドットで区切ります。フィールド名は、camelCaseまたはcamelCase形式で指定できます。便宜上、同じタイプの複数のサブフィールドはかっこ内にリストできます。
次の spreadsheets.get
リクエストの例では、sheets.properties(sheetId,title,sheetType,gridProperties)
のフィールド マスクを使用して、スプレッドシート内のすべてのシートに含まれる SheetProperties
オブジェクトのシート ID、タイトル、SheetType
、GridProperties
のみを取得します。
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)
このメソッド呼び出しに対するレスポンスは、フィールド マスクでリクエストされたコンポーネントを含む Spreadsheet
オブジェクトです。なお、sheetType=OBJECT
に gridProperties
が含まれていないことに注意してください。
{ "sheets": [ { "properties": { "sheetId":SHEET_ID
, "title": "TITLE
", "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 25 } } }, { "properties": { "sheetId":SHEET_ID
, "title": "TITLE
", "sheetType": "OBJECT" } } ] }
フィールド マスクを使用して更新する
オブジェクト内の特定のフィールドのみを更新し、他のフィールドは変更しない必要がある場合があります。spreadsheets.batchUpdate
オペレーション内の更新リクエストでは、フィールド マスクを使用して、変更対象のフィールドを API に伝えます。更新リクエストでは、フィールド マスクで指定されていないフィールドは無視され、現在の値が使用されます。
更新されたメッセージでフィールドを指定せず、そのフィールドをマスクに追加して、フィールドの設定を解除することもできます。これにより、それまで設定されていた値が消去されます。
更新フィールド マスクの構文は、読み取りフィールド マスクと同じです。
次の例では、AddSheetRequest
を使用して Grid
タイプの新しいシートを追加し、最初の行を固定して、新しいシートのタブを赤色にしています。
POST https://sheets.googleapis.com/v1/spreadsheets/spreadsheetId:batchUpdate
{ "spreadsheetId": "SPREADSHEET_ID
", "replies": [ { "addSheet": { "properties": { "sheetId":SHEET_ID
, "title": "TITLE
", "index": 6, "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 26, "frozenRowCount": 1 }, "tabColor": { "red": 0.003921569 }, "tabColorStyle": { "rgbColor": { "red": 0.003921569 } } } } } ] }