開發人員中繼資料功能可讓您將中繼資料與試算表中的各種實體和位置建立關聯。接著，您可以查詢這項中繼資料，並使用這項中繼資料找出與其相關聯的物件。
您可以將中繼資料與資料列、欄、工作表或試算表建立關聯。
開發人員中繼資料可讓您執行下列作業：
將任意資料與試算表中的各種實體和位置建立關聯，例如將
totals與資料欄 D 建立關聯，或將responseId = 1234與第 7 列建立關聯。找出與特定中繼資料鍵或屬性相關聯的所有位置和資料：例如，如果指定與資料欄 D 相關聯的鍵
totals，或指定responseId，則會傳回所有包含responseId中繼資料的資料列，以及與這些資料列相關聯的中繼資料值。找出與特定實體或位置相關聯的所有資料：例如，如果指定資料欄為 D，則傳回與該位置相關聯的所有中繼資料。
透過指定相關的結構描述，擷取位置中的值。舉例來說，如果提供
totals，則會傳回相關欄或列中所含值的表示法；如果提供summary，則會傳回相關工作表資源的表示法。指定相關中繼資料來更新位置中的值：例如，不要透過 A1 符號更新資料列中的值，而是透過指定中繼資料 ID 來更新值。
讀取及寫入中繼資料
spreadsheets.developerMetadata 資源可讓您存取與試算表中位置或物件相關聯的開發人員中繼資料。
關於開發人員中繼資料
本節將說明使用 Google 試算表 API 時，應考量的開發人員中繼資料相關重點。
中繼資料做為代碼
開發人員中繼資料的其中一個用途是標記，可用來命名試算表中的地點，只需使用鍵和地點即可。例如，您可以將 headerRow 與特定資料列建立關聯，或是將 totals 與試算表中的特定欄建立關聯。標記可用於將試算表的部分內容語義繫結至第三方工具或資料庫中的欄位，因此即使試算表有所變更，也不會影響應用程式。
中繼資料做為屬性
透過指定鍵、位置和值建立的中繼資料，會做為與工作表中該位置相關聯的鍵-值組合。舉例來說，您可以將下列項目建立關聯：
formResponseId = resp123與一列lastUpdated = 1477369882與資料欄。
這可讓您儲存及存取與試算表中特定區域或資料相關聯的自訂命名屬性。
專案與文件可見中繼資料
為避免一個開發人員的專案干擾另一個開發人員的中繼資料，我們提供 2 個中繼資料 visibility 設定：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 的開發人員中繼資料值。
如要確認已移除開發人員中繼資料，請使用 spreadsheets.developerMetadata.get 方法，指定已刪除的中繼資料 ID。您應該會收到 404: Not Found HTTP 狀態碼回應，並顯示「No developer metadata with 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，以及一或多個與中繼資料相符的資料篩選器。
顯示範例
在本例中，我們會在要求中提供中繼資料 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，以及一或多個與中繼資料相符的資料篩選器。
這項要求的功能與一般「試算表 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)，以及與中繼資料相符的一或多個 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 個半形字元 (第一個工作表為 30,000 個半形字元、第二個工作表為 30,000 個半形字元，依此類推)。因此，如果試算表有 3 個頁面，最多可包含 120,000 個半形字元的開發人員中繼資料。
developerMetadata 物件的鍵和值屬性中，每個字元都會計入此限制。