デベロッパー メタデータ機能を使用すると、スプレッドシート内のさまざまなエンティティや場所に関連付けることができます。このメタデータをクエリして、関連付けられているオブジェクトを見つけることができます。
メタデータは、行、列、シート、スプレッドシートに関連付けることができます。
デベロッパー メタデータを使用すると、次のようなオペレーションを実行できます。
スプレッドシート内のさまざまなエンティティや場所と任意のデータを関連付ける - たとえば、
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を使用して列を結合します。
これにより、スプレッドシート内の特定の領域やデータに関連付けられたカスタム名前付きプロパティを保存してアクセスできます。
プロジェクトとドキュメントの表示メタデータ
あるデベロッパー プロジェクトが別のデベロッパー プロジェクトのメタデータに干渉しないように、メタデータ visibility 設定が 2 つあります。project と document です。Sheets API を使用すると、プロジェクト メタデータは、作成したデベロッパー プロジェクトからのみ表示およびアクセスできます。ドキュメント メタデータには、ドキュメントへのアクセス権を持つすべてのデベロッパー プロジェクトからアクセスできます。
可視性を明示的に指定していないクエリは、リクエストを行うデベロッパー プロジェクトのドキュメント メタデータとプロジェクト メタデータに一致するものを返します。
一意性
メタデータキーは一意である必要はありませんが、metadataId は一意である必要があります。メタデータを作成して ID フィールドを指定しない場合、API によって ID が割り当てられます。この ID を使用してメタデータを識別できます。キーやその他の属性を使用して、メタデータのセットを識別できます。
メタデータを作成する
メタデータを作成するには、batchUpdate メソッドを使用し、metadataKey、location、visibility を含む createDeveloperMetadataRequest を指定します。必要に応じて、metadataValue または明示的な metadataId を指定できます。
すでに使用されている ID を指定すると、リクエストは失敗します。ID を指定しない場合、API によって ID が割り当てられます。
この例では、リクエストでキー、値、行を指定しています。レスポンスでは、これらのデベロッパー メタデータ値と、割り当てられたメタデータ ID が返されます。
リクエスト
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}レスポンス
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}
}
}
]
}単一のメタデータ アイテムを読み取る
単一の個別のデベロッパー メタデータを取得するには、spreadsheets.developerMetadata.get メソッドを使用し、メタデータを含む spreadsheetId とデベロッパー メタデータの固有の metadataId を指定します。
リクエスト
この例では、リクエストでスプレッドシート ID とメタデータ ID を指定します。レスポンスで、メタデータ ID のデベロッパー メタデータ値が返されます。
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/developerMetadata/metadataId
レスポンス
{
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}複数のメタデータ アイテムを読み取る
複数のデベロッパー メタデータ項目を取得するには、spreadsheets.developerMetadata.search メソッドを使用します。キー、値、ロケーション、公開設定などのプロパティの任意の組み合わせで既存のメタデータと一致する DataFilter を指定する必要があります。
この例では、リクエストで複数のメタデータ ID を指定します。レスポンスでは、各メタデータ ID のデベロッパー メタデータ値が返されます。
リクエスト
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
},
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}レスポンス
{
"matchedDeveloperMetadata": [
{
"developerMetadata": {
"metadataId": metadataId,
"metadataKey": "Revenue",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
},
{
"developerMetadata": {
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}メタデータを更新
デベロッパー メタデータを更新するには、spreadsheets.batchUpdate メソッドを使用し、UpdateDeveloperMetadataRequest を指定します。更新するメタデータをターゲットとする DataFilter、新しい値を含む DeveloperMetadata オブジェクト、更新するフィールドを記述するフィールド マスクを指定する必要があります。
この例では、リクエストでメタデータ ID、シート ID、新しいメタデータキーを指定します。レスポンスでは、これらのデベロッパー メタデータ値と、更新されたメタデータキーが返されます。
リクエスト
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"developerMetadata": {
"location": {
"sheetId": sheetId
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}レスポンス
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}メタデータを削除する
デベロッパー メタデータを削除するには、batchUpdate メソッドを使用し、DeleteDeveloperMetadataRequest を指定します。削除するメタデータを選択するには、DataFilter を指定する必要があります。
この例では、リクエストでメタデータ ID を指定します。レスポンスで、メタデータ ID のデベロッパー メタデータ値が返されます。
デベロッパー メタデータが削除されたことを確認するには、削除されたメタデータ ID を指定して spreadsheets.developerMetadata.get メソッドを使用します。404: Not Found HTTP ステータス コード レスポンスが返されます。メッセージには「ID metadataId のデベロッパー メタデータはありません」と表示されます。
リクエスト
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
}
}
}
]
}レスポンス
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}メタデータに関連付けられた値を読み書きする
関連付けられたデベロッパー メタデータと更新する値を指定して、行と列のセル値を取得して更新することもできます。これを行うには、一致する DataFilter を使用して、以下の適切なメソッドを使用します。
メタデータでセル値を取得する
メタデータでセル値を取得するには、spreadsheets.values.batchGetByDataFilter メソッドを使用します。スプレッドシート ID と、メタデータに一致する 1 つ以上のデータフィルタを指定する必要があります。
この例では、リクエストでメタデータ ID を指定します。レスポンスで、メタデータ ID の行セル値（モデル番号、月間販売数）が返されます。
リクエスト
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"majorDimension": "ROWS"
}レスポンス
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}メタデータでスプレッドシートを取得する
スプレッドシートを取得する際に、spreadsheets.getByDataFilter メソッドを使用してデータのサブセットを返すことができます。スプレッドシート ID と、メタデータに一致する 1 つ以上のデータフィルタを指定する必要があります。
このリクエストは、指定されたデータフィルタに一致するメタデータのリストによって、どのシート、グリッドデータ、メタデータを含むその他のオブジェクト リソースが返されるかが決定される点を除き、通常のスプレッドシート GET リクエストとして機能します。includeGridData が true に設定されている場合、指定されたグリッド範囲と交差するグリッドデータもシートに対して返されます。
この例では、メタデータ ID を指定し、リクエストで includeGridData を false に設定します。レスポンスでは、スプレッドシートとシートの両方のプロパティが返されます。
リクエスト
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"includeGridData": false
}レスポンス
{ "spreadsheetId": spreadsheetId, "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": sheetId, "title": "Sheet7", "index": 7, "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 26 } } } ], "spreadsheetUrl": spreadsheetUrl }
メタデータで値を更新する
特定のメタデータに一致するセル値を更新するには、spreadsheets.values.batchUpdateByDataFilter メソッドを使用します。スプレッドシート ID、valueInputOption、メタデータと一致する 1 つ以上の DataFilterValueRange を指定する必要があります。
この例では、リクエストでメタデータ ID と更新された行の値を指定します。レスポンスでは、メタデータ ID の更新されたプロパティとデータの両方が返されます。
リクエスト
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}レスポンス
{
"spreadsheetId": spreadsheetId,
"totalUpdatedRows": 1,
"totalUpdatedColumns": 2,
"totalUpdatedCells": 2,
"totalUpdatedSheets": 1,
"responses": [
{
"updatedRange": "Sheet7!A7:B7",
"updatedRows": 1,
"updatedColumns": 2,
"updatedCells": 2,
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"updatedData": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
}
]
}メタデータで値をクリアする
特定のメタデータに一致するセル値をクリアするには、spreadsheets.values.batchClearByDataFilter メソッドを使用します。消去するメタデータを選択するには、データフィルタを指定する必要があります。
リクエスト
この例では、リクエストでメタデータ ID を指定します。レスポンスで、スプレッドシート ID とクリアされた範囲が返されます。
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}レスポンス
{
"spreadsheetId": spreadsheetId,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}メタデータ ストレージの上限
スプレッドシートに保存できるメタデータの合計量には上限があります。この上限は文字数で測定され、次の 2 つのコンポーネントで構成されます。
| 項目 | 保存容量の上限の割り当て |
|---|---|
| スプレッドシート | 30,000 文字 |
| スプレッドシート内の各シート | 30,000 文字 |
スプレッドシートには最大 30,000 文字を保存できます。また、スプレッドシート内の各シートに 30,000 文字を保存できます（シート 1 に 30,000 文字、シート 2 に 30,000 文字など）。したがって、3 ページのスプレッドシートには、最大 120,000 文字のデベロッパー メタデータを含めることができます。
developerMetadata オブジェクトのキー属性と値属性の各文字が、この上限にカウントされます。