借助元数据功能，您可以将元数据与电子表格中的各种实体和位置相关联。然后，您可以查询此元数据，并使用它来查找与其关联的对象。
您可以将元数据与行、列、工作表或电子表格相关联。
关于元数据
以下内容介绍了与 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
方法，
并提供包含metadataKey、location和visibility值的
CreateDeveloperMetadataRequest
（来自
spreadsheets.developerMetadata资源）。您可以选择指定 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 个字符（工作表 1 为 30,000 个字符，工作表 2 为 30,000 个字符，依此类推）。因此，包含三个工作表的电子表格最多可以包含 120,000 个字符的元数据。
资源中的 metadataKey 和 metadataValue 字段中的每个字符都计入此限制。spreadsheets.developerMetadata