借助元数据功能，您可以将元数据与电子表格中的各种实体和位置相关联。然后，您可以查询此元数据，并使用它来查找与其关联的对象。
您可以将元数据与行、列、工作表或电子表格相关联。
元数据简介
下面介绍了一些关键的元数据方面，您在使用 Sheets API 时应考虑这些方面：
以标记形式呈现的元数据：开发者元数据的一种用途是标记，该标记仅使用键和位置来命名电子表格中的位置。例如，您可以将
headerRow与工作表中的特定行相关联，或将totals与工作表中的特定列相关联。标记可用于将电子表格的部分内容从语义上绑定到第三方工具或数据库中的字段，这样一来，对电子表格的更改就不会破坏您的应用。作为属性的元数据：通过指定键、位置和值创建的元数据，充当与工作表中的相应位置关联的键值对。例如，您可以关联以下内容：
formResponseId = resp123（带行）lastUpdated = 1477369882（含列）
这样，您就可以存储和访问与电子表格中的特定区域或数据关联的自定义命名属性。
项目与文档可见元数据：为防止一个开发者项目干扰另一个项目的元数据，我们提供了两种元数据
visibility设置：project和document。使用 Sheets API 时，project元数据只能从创建它的 Google Cloud 项目中查看和访问。任何有权访问相应文档的 Google Cloud 项目都可以访问document元数据。未明确指定
visibility的查询会返回发出请求的 Google Cloud 项目的匹配document元数据和匹配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，返回关联的 Sheet 资源的表示形式。通过指定关联的元数据来更新位置中的值：例如，不通过 A1 标记法更新行中的值，而是通过指定元数据 ID 来更新值。
读取和写入元数据
spreadsheets.developerMetadata 资源可用于访问与电子表格中的位置或对象相关联的元数据。开发者元数据可用于将任意数据与电子表格的各个部分相关联。在修改电子表格时，元数据仍会与这些位置相关联。
创建元数据
如需创建元数据，请对 spreadsheets 资源使用 batchUpdate 方法，并提供一个 CreateDeveloperMetadataRequest，其中包含来自 spreadsheets.developerMetadata 资源的 metadataKey、location 和 visibility 值。您可以选择指定 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，该 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 状态代码响应，其中包含一条消息，指出“没有 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 个字符 |
您最多可以为电子表格存储 3 万个字符。此外，您还可以在电子表格中为每个工作表存储 30,000 个字符（工作表 1 为 30,000 个字符，工作表 2 为 30,000 个字符，依此类推）。因此，包含三个工作表的电子表格最多可包含 12 万个字符的元数据。
spreadsheets.developerMetadata 资源的 metadataKey 和 metadataValue 字段中的每个字符都会计入此限制。