メタデータ機能を使用すると、スプレッドシート内のさまざまなエンティティや場所に関連付けることができます。このメタデータをクエリして、関連付けられているオブジェクトを見つけることができます。
メタデータは、行、列、シート、スプレッドシートに関連付けることができます。
メタデータを生成して、次のようなオペレーションを実行できます。
スプレッドシート内のさまざまなエンティティや場所と任意のデータを関連付ける: たとえば、
totalsを D 列に関連付けたり、responseId = 1234を 7 行に関連付けたりします。特定のメタデータキーまたは属性に関連付けられているすべての場所とデータを見つける: たとえば、列 D に関連付けられているキー
totalsが指定されている場合、またはresponseIdが指定されている場合、responseIdメタデータとそれに関連付けられているメタデータ値を含むすべての行を返します。特定のエンティティまたは場所に関連付けられているすべてのデータを検索する: たとえば、列 D が指定された場合、その場所に関連付けられているすべてのメタデータを返します。
関連するメタデータを指定して、ロケーション内の値を取得する: たとえば、
totalsが指定された場合は、関連付けられた列または行に含まれる値の表現を返します。summaryが指定された場合は、関連付けられたシート リソースの表現を返します。関連付けられたメタデータを指定して、ロケーションの値を更新する: たとえば、A1 形式で 1 つの行の値を更新する代わりに、メタデータ ID を指定して値を更新します。
メタデータの読み取りと書き込み
spreadsheets.developerMetadata リソースは、スプレッドシート内の場所またはオブジェクトに関連付けられたメタデータへのアクセスを提供します。
メタデータについて
このセクションでは、Sheets API を使用する際に考慮すべきメタデータの重要な側面について説明します。
タグとしてのメタデータ: デベロッパー メタデータの用途の 1 つは、キーと場所のみを使用してスプレッドシート内の場所を指定するタグです。たとえば、
headerRowをシート内の特定の行に関連付けたり、totalsをシート内の特定の列に関連付けたりできます。タグを使用すると、スプレッドシートの一部をサードパーティ製ツールやデータベースのフィールドに意味的にバインドできるため、スプレッドシートを変更してもアプリが壊れることはありません。プロパティとしてのメタデータ: キー、場所、値を指定して作成されたメタデータ。シート内のその場所に関連付けられた Key-Value ペアとして機能します。たとえば、次のような関連付けが可能です。
formResponseId = resp123（行あり）- 列を含む
lastUpdated = 1477369882
これにより、スプレッドシート内の特定の領域やデータに関連付けられたカスタム名前付きプロパティを保存してアクセスできます。
プロジェクトとドキュメントの可視メタデータ: 1 つのデベロッパー プロジェクトが別のプロジェクトのメタデータに干渉しないように、
visibilityメタデータ設定（projectとdocument）が 2 つあります。Sheets API を使用すると、プロジェクト メタデータは、作成した Google Cloud プロジェクトからのみ表示およびアクセスできます。ドキュメントのメタデータには、ドキュメントにアクセスできる Google Cloud プロジェクトからアクセスできます。可視性を明示的に指定しないクエリは、リクエストを行う Google Cloud プロジェクトの一致するドキュメント メタデータと一致するプロジェクト メタデータを返します。
一意性: メタデータキーは一意である必要はありませんが、
metadataIdは一意である必要があります。メタデータを作成して ID フィールドを指定しない場合、API によって ID が割り当てられます。この ID を使用してメタデータを識別できます。キーやその他の属性を使用して、メタデータのセットを識別できます。
メタデータを作成する
メタデータを作成するには、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 フィールドの各文字がこの上限にカウントされます。