中繼資料功能可讓您將中繼資料與試算表中的各種實體和位置建立關聯。接著，您可以查詢這項中繼資料，並用來尋找與其相關聯的物件。
您可以將中繼資料與列、欄、工作表或試算表建立關聯。
關於中繼資料
使用 Google 試算表 API 時，請注意下列中繼資料的重要事項：
中繼資料做為標記：開發人員中繼資料的用途之一是標記，只使用鍵和位置資訊，即可命名試算表中的位置。舉例來說，您可以將
headerRow與工作表中的特定資料列建立關聯，或將totals與特定資料欄建立關聯。標記可用於將試算表的部分內容，以語意方式繫結至第三方工具或資料庫中的欄位，因此試算表的變更不會導致應用程式中斷。中繼資料做為屬性：指定鍵、位置和值所建立的中繼資料，做為試算表中與該位置相關聯的鍵值組合。舉例來說，您可以建立下列關聯：
formResponseId = resp123個資料列lastUpdated = 1477369882欄
這項功能可讓您儲存及存取與試算表特定區域或資料相關聯的自訂命名屬性。
專案與文件可見中繼資料：為避免一個開發人員專案干擾另一個專案的中繼資料，系統提供兩種中繼資料
visibility設定：project和document。使用 Sheets API 時，project中繼資料只能由建立該資料的 Google Cloud 專案查看及存取。只要有權存取文件，就能從任何 Google Cloud 專案存取document中繼資料。如果查詢未明確指定
visibility，系統會傳回相符的document中繼資料，以及發出要求的 Google Cloud 專案相符的project中繼資料。獨特性：中繼資料鍵不必是獨一無二，但
metadataId必須是獨一無二。如果您建立中繼資料時未指定 ID 欄位，API 會指派 ID。這個 ID 可用來識別中繼資料，而鍵和其他屬性則可用來識別中繼資料集。透過 API 要求傳回中繼資料：
DataFilter物件是 API 呼叫的一部分，用於說明要從 API 要求選取或傳回的資料。單一
DataFilter物件只能指定一種篩選條件來尋找資料：developerMetadataLookup： 選取與指定開發人員中繼資料相關聯的資料，且符合條件。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 標記更新資料列中的值，而是透過指出中繼資料 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 的開發人員中繼資料值。
如要確認開發人員中繼資料已移除，請使用 spreadsheets.developerMetadata.get 方法，並指定已刪除的中繼資料 ID。您應該會收到 404: Not Found HTTP 狀態碼回應，並顯示「No developer metadata with ID METADATA_ID.
要求
{
"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 和一或多個符合中繼資料的資料篩選器。
在本例中，我們會在要求中提供中繼資料 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 和一或多個符合中繼資料的資料篩選器。
這項要求與一般「試算表 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，以及一或多個與中繼資料相符的 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"
]
}中繼資料儲存空間限制
試算表可儲存的中繼資料總量有限。這項限制是以字元為單位，由下列兩部分組成：
| 項目 | 分配儲存空間上限 |
|---|---|
| 試算表 | 30,000 個字元 |
| 試算表中的每個工作表 | 30,000 個字元 |
試算表最多可儲存 30,000 個字元。此外，每個試算表中的工作表最多可儲存 30,000 個半形字元 (工作表一 30,000 個、工作表二 30,000 個，依此類推)。因此，如果試算表有三個工作表，中繼資料最多可包含 120,000 個字元。
spreadsheets.developerMetadata 資源的 metadataKey 和 metadataValue 欄位中，每個字元都會計入這項限制。