メタデータの読み取り、書き込み、検索

メタデータ機能を使用すると、スプレッドシート内のさまざまなエンティティやロケーションにメタデータを関連付けることができます。このメタデータをクエリして、関連付けられているオブジェクトを見つけることができます。

メタデータは、行、列、シート、スプレッドシートに関連付けることができます。

メタデータについて

以下に、Sheets API を使用する際に考慮すべきメタデータの重要な側面をいくつか説明します。

タグとしてのメタデータ: デベロッパーメタデータの用途の 1 つは、キーと場所のみを使用してスプレッドシート内の場所を指定するタグです。たとえば、headerRow をシート内の特定の行に関連付けたり、totals をシート内の特定の列に関連付けたりできます。タグを使用すると、スプレッドシートの一部をサードパーティ製ツールやデータベースのフィールドに意味的にバインドできるため、スプレッドシートを変更してもアプリが壊れることはありません。
プロパティとしてのメタデータ: キー、場所、値を指定して作成されたメタデータ。シート内のその場所に関連付けられた Key-Value ペアとして機能します。たとえば、次のような関連付けが可能です。
- formResponseId = resp123（行あり）
- 列を含む lastUpdated = 1477369882
これにより、スプレッドシート内の特定の領域やデータに関連付けられたカスタム名前付きプロパティを保存してアクセスできます。
プロジェクトとドキュメントの可視メタデータ: 1 つのデベロッパープロジェクトが別のプロジェクトのメタデータに干渉しないように、visibility の 2 つのメタデータ設定（project と document）があります。Sheets API を使用する場合、project メタデータは、作成した Google Cloud プロジェクトからのみ表示およびアクセスできます。document メタデータには、ドキュメントにアクセスできる Google Cloud プロジェクトからアクセスできます。

visibility を明示的に指定しないクエリは、リクエストを行う Google Cloud プロジェクトに一致する document メタデータと一致する project メタデータを返します。

プロジェクトで表示可能なデベロッパーメタデータをセキュリティメカニズムとして使用したり、シークレットの保存に使用したりしないでください。メタデータは、ドキュメントの閲覧権限を持つユーザーに公開される可能性があります。
一意性: メタデータキーは一意である必要はありませんが、metadataId は一意である必要があります。メタデータを作成して ID フィールドを指定しない場合、API によって ID が割り当てられます。この ID を使用してメタデータを識別できます。キーやその他の属性を使用して、メタデータのセットを識別できます。

メタデータの作成時に独自の `metadataId` を指定できますが、スプレッドシート API に割り当てさせることをおすすめします。
API リクエストでメタデータを返す: DataFilter オブジェクトは、API リクエストから選択または返されるデータを記述する API 呼び出しの一部です。

1 つの DataFilter オブジェクトで指定できるのは、データを検索するためのフィルタ条件の 1 つのタイプのみです。
- developerMetadataLookup: 条件に一致する指定されたデベロッパーメタデータに関連付けられたデータを選択します。
- a1Range: 指定された A1 形式の範囲と一致するデータを選択します。例: Sheet1!A1:B10
- gridRange: ゼロベースのインデックスを使用して、指定されたグリッド範囲と一致するデータを選択します。例: Sheet1!A3:B4 == sheetId: 123456, startRowIndex: 2, endRowIndex: 4, startColumnIndex: 0, endColumnIndex: 2
複数の地域や条件でフィルタするには、単一の API リクエストで複数の DataFilter オブジェクトを使用します。spreadsheets.values.batchGetByDataFilter メソッドなどのバッチリクエストに DataFilter オブジェクトの配列またはリストを指定します。リクエスト内のデータフィルタのいずれかに一致する範囲は、返されるか変更されます。

詳細については、メタデータに関連付けられた値を読み書きするをご覧ください。

ユースケース

メタデータの管理のユースケースの例を次に示します。

スプレッドシート内のさまざまなエンティティや場所と任意のデータを関連付ける: たとえば、totals を D 列に関連付けたり、responseId = 1234 を 7 行に関連付けたりします。
特定のメタデータキーまたは属性に関連付けられているすべての場所とデータを見つける: たとえば、列 D に関連付けられているキー totals が指定されている場合、または responseId が指定されている場合、responseId メタデータとそれに関連付けられているメタデータ値を含むすべての行を返します。
特定のエンティティまたは場所に関連付けられているすべてのデータを検索する: たとえば、列 D が指定された場合、その場所に関連付けられているすべてのメタデータを返します。
関連するメタデータを指定して、ロケーション内の値を取得する: たとえば、totals が指定された場合は、関連する列または行に含まれる値の表現を返します。summary が指定された場合は、関連するシートリソースの表現を返します。
関連付けられたメタデータを指定して、ロケーションの値を更新する: たとえば、A1 形式で 1 つの行の値を更新する代わりに、メタデータ ID を指定して値を更新します。

メタデータの読み取りと書き込み

spreadsheets.developerMetadata リソースは、スプレッドシート内の場所またはオブジェクトに関連付けられたメタデータへのアクセスを提供します。デベロッパーメタデータを使用すると、スプレッドシートのさまざまな部分に任意のデータを関連付けることができます。スプレッドシートを編集しても、メタデータはこれらの場所に関連付けられたままになります。

メタデータを作成する

メタデータを作成するには、spreadsheets リソースで batchUpdate メソッドを使用し、spreadsheets.developerMetadata リソースから metadataKey、location、visibility の値を含む CreateDeveloperMetadataRequest を指定します。必要に応じて、metadataValue または明示的な metadataId を指定できます。

すでに使用されている ID を指定すると、リクエストは失敗します。ID を指定しない場合、API によって ID が割り当てられます。

この例では、リクエストでキー、値、行を指定しています。レスポンスでは、これらのデベロッパーメタデータ値と、割り当てられたメタデータ ID が返されます。

リクエスト

{
  "requests": [
    {
      "createDeveloperMetadata": {
        "developerMetadata": {
          "location": {
            "dimensionRange": {
              "sheetId": SHEET_ID,
              "dimension": "ROWS",
              "startIndex": 6,
              "endIndex": 7
            }
          },
          "visibility": "DOCUMENT",
          "metadataKey": "Sales",
          "metadataValue": "2022"
        }
      }
    }
  ]
}

レスポンス

{
  "spreadsheetId": SPREADSHEET_ID,
  "replies": [
    {
      "createDeveloperMetadata": {
        "developerMetadata": {
          "metadataId": METADATA_ID,
          "metadataKey": "Sales",
          "metadataValue": "2022",
          "location": {
            "locationType": "ROW",
            "dimensionRange": {
              "sheetId": SHEET_ID,
              "dimension": "ROWS",
              "startIndex": 6,
              "endIndex": 7
            }
          },
          "visibility": "DOCUMENT"
        }
      }
    }
  ]
}

単一のメタデータアイテムを読み取る

単一の個別のデベロッパーメタデータを取得するには、spreadsheets.developerMetadata.get メソッドを使用し、メタデータを含む spreadsheetId とデベロッパーメタデータの固有の metadataId を指定します。

リクエスト

この例では、リクエストでスプレッドシート ID とメタデータ ID を指定します。レスポンスでは、メタデータ ID のデベロッパーメタデータ値が返されます。

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/developerMetadata/METADATA_ID

レスポンス

{
  "metadataId": METADATA_ID,
  "metadataKey": "Sales",
  "metadataValue": "2022",
  "location": {
    "locationType": "ROW",
    "dimensionRange": {
      "sheetId": SHEET_ID,
      "dimension": "ROWS",
      "startIndex": 6,
      "endIndex": 7
    }
  },
  "visibility": "DOCUMENT"
}

複数のメタデータアイテムを読み取る

複数のデベロッパーメタデータ項目を取得するには、spreadsheets.developerMetadata.search メソッドを使用します。キー、値、ロケーション、公開設定などのプロパティの任意の組み合わせで既存のメタデータと一致する DataFilter を指定する必要があります。

この例では、リクエストで複数のメタデータ ID を指定します。レスポンスで、各メタデータ ID のデベロッパーメタデータ値が返されます。

リクエスト

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": METADATA_ID
      }
    },
    {
      "developerMetadataLookup": {
        "metadataId": METADATA_ID
      }
    }
  ]
}

レスポンス

{
  "matchedDeveloperMetadata": [
    {
      "developerMetadata": {
        "metadataId": METADATA_ID,
        "metadataKey": "Revenue",
        "metadataValue": "2022",
        "location": {
          "locationType": "SHEET",
          "sheetId": SHEET_ID
        },
        "visibility": "DOCUMENT"
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": METADATA_ID
          }
        }
      ]
    },
    {
      "developerMetadata": {
        "metadataId": METADATA_ID,
        "metadataKey": "Sales",
        "metadataValue": "2022",
        "location": {
          "locationType": "SHEET",
          "sheetId": SHEET_ID
        },
        "visibility": "DOCUMENT"
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": METADATA_ID
          }
        }
      ]
    }
  ]
}

メタデータを更新

デベロッパーメタデータを更新するには、spreadsheets.batchUpdate メソッドを使用し、UpdateDeveloperMetadataRequest を指定します。更新するメタデータをターゲットとする DataFilter、新しい値を含む spreadsheets.developerMetadata リソース、更新するフィールドを記述するフィールドマスクを指定する必要があります。

この例では、リクエストでメタデータ ID、シート ID、新しいメタデータキーを指定します。レスポンスでは、これらのデベロッパーメタデータ値と、更新されたメタデータキーが返されます。

リクエスト

{
  "requests": [
    {
      "updateDeveloperMetadata": {
        "dataFilters": [
          {
            "developerMetadataLookup": {
              "metadataId": METADATA_ID
            }
          }
        ],
        "developerMetadata": {
          "location": {
            "sheetId": SHEET_ID
          },
          "metadataKey": "SalesUpdated"
        },
        "fields": "location,metadataKey"
      }
    }
  ]
}

レスポンス

{
  "spreadsheetId": SPREADSHEET_ID,
  "replies": [
    {
      "updateDeveloperMetadata": {
        "developerMetadata": [
          {
            "metadataId": METADATA_ID,
            "metadataKey": "SalesUpdated",
            "metadataValue": "2022",
            "location": {
              "locationType": "SHEET",
              "sheetId": SHEET_ID
            },
            "visibility": "DOCUMENT"
          }
        ]
      }
    }
  ]
}

メタデータを削除する

デベロッパーメタデータを削除するには、batchUpdate メソッドを使用し、DeleteDeveloperMetadataRequest を指定します。削除するメタデータを選択するには、DataFilter を指定する必要があります。

この例では、リクエストでメタデータ ID を指定します。レスポンスでは、メタデータ ID のデベロッパーメタデータ値が返されます。

デベロッパーメタデータが削除されたことを確認するには、削除されたメタデータ ID を指定して spreadsheets.developerMetadata.get メソッドを使用します。「ID METADATA_ID のデベロッパーメタデータはありません」というメッセージを含む 404: Not Found HTTP ステータスコードレスポンスが返されます。

リクエスト

{
  "requests": [
    {
      "deleteDeveloperMetadata": {
        "dataFilter": {
          "developerMetadataLookup": {
            "metadataId": METADATA_ID
          }
        }
      }
    }
  ]
}

レスポンス

{
  "spreadsheetId": SPREADSHEET_ID,
  "replies": [
    {
      "deleteDeveloperMetadata": {
        "deletedDeveloperMetadata": [
          {
            "metadataId": METADATA_ID,
            "metadataKey": "SalesUpdated",
            "metadataValue": "2022",
            "location": {
              "locationType": "SHEET",
              "sheetId": SHEET_ID
            },
            "visibility": "DOCUMENT"
          }
        ]
      }
    }
  ]
}

メタデータに関連付けられた値の読み取りと書き込み

関連付けられたデベロッパーメタデータと更新する値を指定して、行と列のセル値を取得して更新することもできます。これを行うには、一致する DataFilter を使用して、次のいずれかの方法を使用します。

メタデータでセル値を取得する

メタデータでセル値を取得するには、spreadsheets.values.batchGetByDataFilter メソッドを使用します。スプレッドシート ID と、メタデータに一致する 1 つ以上のデータフィルタを指定する必要があります。

この例では、リクエストでメタデータ ID を指定します。レスポンスで、メタデータ ID の行セル値（モデル番号、月間販売数）が返されます。

リクエスト

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": METADATA_ID
      }
    }
  ],
  "majorDimension": "ROWS"
}

レスポンス

{
  "spreadsheetId": SPREADSHEET_ID,
  "valueRanges": [
    {
      "valueRange": {
        "range": "Sheet7!A7:Z7",
        "majorDimension": "ROWS",
        "values": [
          [
            "W-24",
            "74"
          ]
        ]
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": METADATA_ID
          }
        }
      ]
    }
  ]
}

メタデータでスプレッドシートを取得する

スプレッドシートを取得するときに、spreadsheets.getByDataFilter メソッドを使用してデータのサブセットを返すことができます。スプレッドシート ID と、メタデータに一致する 1 つ以上のデータフィルタを指定する必要があります。

このリクエストは、指定されたデータフィルタに一致するメタデータのリストによって、どのシート、グリッドデータ、メタデータを含むその他のオブジェクトリソースが返されるかが決定される点を除き、通常のスプレッドシート GET リクエストとして機能します。includeGridData が true に設定されている場合、指定されたグリッド範囲と交差するグリッドデータもシートに対して返されます。リクエストでフィールドマスクが設定されている場合、includeGridData フィールドは無視されます。

この例では、メタデータ ID を指定し、リクエストで includeGridData を false に設定します。レスポンスは、スプレッドシートとシートの両方のプロパティを返します。

リクエスト

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": METADATA_ID
      }
    }
  ],
  "includeGridData": false
}

レスポンス

{
  "spreadsheetId": SPREADSHEET_ID,
  "properties": {
    "title": "Sales Sheet",
    "locale": "en_US",
    "autoRecalc": "ON_CHANGE",
    "timeZone": "America/Los_Angeles",
    "defaultFormat": {
      "backgroundColor": {
        "red": 1,
        "green": 1,
        "blue": 1
      },
      "padding": {
        "top": 2,
        "right": 3,
        "bottom": 2,
        "left": 3
      },
      "verticalAlignment": "BOTTOM",
      "wrapStrategy": "OVERFLOW_CELL",
      "textFormat": {
        "foregroundColor": {},
        "fontFamily": "arial,sans,sans-serif",
        "fontSize": 10,
        "bold": false,
        "italic": false,
        "strikethrough": false,
        "underline": false,
        "foregroundColorStyle": {
          "rgbColor": {}
        }
      },
      "backgroundColorStyle": {
        "rgbColor": {
          "red": 1,
          "green": 1,
          "blue": 1
        }
      }
    },
    "spreadsheetTheme": {
      "primaryFontFamily": "Arial",
      "themeColors": [
        {
          "colorType": "TEXT",
          "color": {
            "rgbColor": {}
          }
        },
        {
          "colorType": "BACKGROUND",
          "color": {
            "rgbColor": {
              "red": 1,
              "green": 1,
              "blue": 1
            }
          }
        },
        {
          "colorType": "ACCENT1",
          "color": {
            "rgbColor": {
              "red": 0.25882354,
              "green": 0.52156866,
              "blue": 0.95686275
            }
          }
        },
        {
          "colorType": "ACCENT2",
          "color": {
            "rgbColor": {
              "red": 0.91764706,
              "green": 0.2627451,
              "blue": 0.20784314
            }
          }
        },
        {
          "colorType": "ACCENT3",
          "color": {
            "rgbColor": {
              "red": 0.9843137,
              "green": 0.7372549,
              "blue": 0.015686275
            }
          }
        },
        {
          "colorType": "ACCENT4",
          "color": {
            "rgbColor": {
              "red": 0.20392157,
              "green": 0.65882355,
              "blue": 0.3254902
            }
          }
        },
        {
          "colorType": "ACCENT5",
          "color": {
            "rgbColor": {
              "red": 1,
              "green": 0.42745098,
              "blue": 0.003921569
            }
          }
        },
        {
          "colorType": "ACCENT6",
          "color": {
            "rgbColor": {
              "red": 0.27450982,
              "green": 0.7411765,
              "blue": 0.7764706
            }
          }
        },
        {
          "colorType": "LINK",
          "color": {
            "rgbColor": {
              "red": 0.06666667,
              "green": 0.33333334,
              "blue": 0.8
            }
          }
        }
      ]
    }
  },
  "sheets": [
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "Sheet7",
        "index": 7,
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 1000,
          "columnCount": 26
        }
      }
    }
  ],
  "spreadsheetUrl": SPREADSHEET_URL
}

メタデータで値を更新する

特定のメタデータに一致するセル値を更新するには、spreadsheets.values.batchUpdateByDataFilter メソッドを使用します。スプレッドシート ID（valueInputOption）と、メタデータに一致する 1 つ以上の DataFilterValueRange 値を指定する必要があります。

この例では、リクエストでメタデータ ID と更新された行の値を指定します。レスポンスでは、メタデータ ID の更新されたプロパティとデータが返されます。

リクエスト

{
  "data": [
    {
      "dataFilter": {
        "developerMetadataLookup": {
          "metadataId": METADATA_ID
        }
      },
      "majorDimension": "ROWS",
      "values": [
        [
          "W-24",
          "84"
        ]
      ]
    }
  ],
  "includeValuesInResponse": true,
  "valueInputOption": "USER_ENTERED"
}

レスポンス

{
  "spreadsheetId": SPREADSHEET_ID,
  "totalUpdatedRows": 1,
  "totalUpdatedColumns": 2,
  "totalUpdatedCells": 2,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "updatedRange": "Sheet7!A7:B7",
      "updatedRows": 1,
      "updatedColumns": 2,
      "updatedCells": 2,
      "dataFilter": {
        "developerMetadataLookup": {
          "metadataId": METADATA_ID
        }
      },
      "updatedData": {
        "range": "Sheet7!A7:Z7",
        "majorDimension": "ROWS",
        "values": [
          [
            "W-24",
            "84"
          ]
        ]
      }
    }
  ]
}

メタデータで値をクリアする

特定のメタデータに一致するセル値をクリアするには、spreadsheets.values.batchClearByDataFilter メソッドを使用します。消去するメタデータを選択するには、データフィルタを指定する必要があります。

リクエスト

この例では、リクエストでメタデータ ID を指定します。レスポンスで、スプレッドシート ID とクリアされた範囲が返されます。

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": METADATA_ID
      }
    }
  ]
}

レスポンス

{
  "spreadsheetId": SPREADSHEET_ID,
  "clearedRanges": [
    "Sheet7!A7:Z7"
  ]
}

メタデータストレージの上限

スプレッドシートに保存できるメタデータの合計量には上限があります。この上限は文字数で測定され、次の 2 つのコンポーネントで構成されます。

項目	保存容量の上限の割り当て
スプレッドシート	30,000 文字
スプレッドシート内の各シート	30,000 文字

スプレッドシートには最大 30,000 文字を保存できます。また、スプレッドシート内の各シートに 30,000 文字を保存できます（シート 1 に 30,000 文字、シート 2 に 30,000 文字など）。したがって、3 つのシートを含むスプレッドシートには、最大 120,000 文字のメタデータを含めることができます。

spreadsheets.developerMetadata リソースの metadataKey フィールドと metadataValue フィールドの各文字がこの上限にカウントされます。

メタデータの読み取り、書き込み、検索 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

メタデータについて

ユースケース

メタデータの読み取りと書き込み

メタデータを作成する

単一のメタデータ アイテムを読み取る

複数のメタデータ アイテムを読み取る

メタデータを更新

メタデータを削除する

メタデータに関連付けられた値の読み取りと書き込み

メタデータでセル値を取得する

メタデータでスプレッドシートを取得する

メタデータで値を更新する

メタデータで値をクリアする

メタデータ ストレージの上限

関連トピック

メタデータの読み取り、書き込み、検索

単一のメタデータアイテムを読み取る

複数のメタデータアイテムを読み取る

メタデータストレージの上限