Функция метаданных разработчика позволяет связывать метаданные с различными объектами и местоположениями в электронной таблице. Затем вы можете запросить эти метаданные и использовать их для поиска объектов, с которыми они связаны.
Вы можете связать метаданные со строками, столбцами, листами или электронной таблицей.
Метаданные разработчика позволяют выполнять такие операции, как:
Свяжите произвольные данные с различными объектами и местоположениями в электронной таблице . Например, свяжите
totalsсо столбцом D илиresponseId = 1234со строкой 7.Найдите все местоположения и данные, связанные с определенным ключом или атрибутом метаданных . Например, учитывая итоговые
totalsключей, связанные со столбцом D, или заданныйresponseId, верните все строки с метаданнымиresponseIdи значением метаданных, связанным с ними.Найти все данные, связанные с определенным объектом или местоположением . Например, для данного столбца D вернуть все метаданные, связанные с этим местоположением.
Извлечение значений в местоположении путем указания связанных метаданных . Например, если
totalsвозвращают представление значений, содержащихся в связанном столбце или строке, или еслиsummaryвозвращает представление связанного ресурса Sheet.Обновите значения в местоположении, указав связанные метаданные. Например, вместо обновления значений в строке с помощью нотации A1 обновите значения, указав идентификатор метаданных.
Чтение и запись метаданных
Ресурс Spreadsheets.developerMetadata предоставляет доступ к метаданным разработчика, связанным с местоположением или объектом в электронной таблице.
О метаданных разработчика
В этом разделе описаны некоторые ключевые аспекты метаданных разработчика, которые следует учитывать при работе с Sheets API.
Метаданные в виде тегов
Одним из вариантов использования метаданных разработчика является тег , который называет местоположение в электронной таблице, используя только ключ и местоположение. Например, вы можете связать headerRow с определенной строкой или totals с определенным столбцом на листе. Теги можно использовать для семантической привязки частей электронной таблицы к полям стороннего инструмента или базы данных, поэтому изменения в электронной таблице не повредят вашему приложению.
Метаданные как свойства
Метаданные, созданные путем указания ключа, местоположения и значения , действуют как пара ключ-значение, связанная с этим местоположением на листе. Например, вы можете связать:
-
formResponseId = resp123со строкой -
lastUpdated = 1477369882со столбцом.
Это позволяет хранить и получать доступ к свойствам с настраиваемыми именами, связанным с определенными областями или данными в электронной таблице.
Видимые метаданные проекта и документа
Чтобы один проект разработчика не мешал метаданным другого, существует 2 настройки visibility метаданных: project и document . Используя API Таблиц, метаданные проекта видны и доступны только из проекта разработчика, который их создал. Метаданные документа доступны из любого проекта разработчика, имеющего доступ к документу.
Запросы, которые явно не указывают видимость, возвращают соответствующие метаданные документа и соответствующие метаданные проекта для проекта разработчика, сделавшего запрос.
Уникальность
Ключи метаданных не обязательно должны быть уникальными, но metadataId должен быть уникальным. Если вы создаете метаданные и оставляете поле идентификатора неуказанным, API присваивает его. Этот идентификатор можно использовать для идентификации метаданных, а ключи и другие атрибуты можно использовать для идентификации наборов метаданных.
Создать метаданные
Чтобы создать метаданные, используйте метод patchUpdate и предоставьте createDeveloperMetadataRequest с metadataKey , location и visibility . При желании вы можете указать metadataValue или явный metadataId .
Если вы укажете идентификатор, который уже используется, запрос будет неудачным. Если вы не укажете идентификатор, API его назначит.
Показать пример
В этом примере мы предоставляем ключ, значение и строку в запросе. Ответ возвращает эти значения метаданных разработчика, а также назначенный идентификатор метаданных.
Запрос
{
"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 метаданных разработчика.
Показать пример
Запрос
В этом примере мы предоставляем в запросе идентификатор электронной таблицы и идентификатор метаданных. Ответ возвращает значения метаданных разработчика для идентификатора метаданных.
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 , который соответствует любым существующим метаданным для любой комбинации свойств, таких как ключ, значение, местоположение или видимость.
Показать пример
В этом примере мы предоставляем в запросе несколько идентификаторов метаданных. Ответ возвращает значения метаданных разработчика для каждого идентификатора метаданных.
Запрос
{
"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 с новыми значениями и маску поля , описывающую поля, которые необходимо обновить.
Показать пример
В этом примере мы предоставляем в запросе идентификатор метаданных, идентификатор листа и новый ключ метаданных. Ответ возвращает эти значения метаданных разработчика, а также обновленный ключ метаданных.
Запрос
{
"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"
}
]
}
}
]
}Удалить метаданные
Чтобы удалить метаданные разработчика, используйте метод patchUpdate и укажите DeleteDeveloperMetadataRequest . Вам нужно будет указать DataFilter , чтобы выбрать метаданные, которые вы хотите удалить.
Показать пример
В этом примере мы предоставляем идентификатор метаданных в запросе. Ответ возвращает значения метаданных разработчика для идентификатора метаданных.
Чтобы подтвердить удаление метаданных разработчика, используйте метод Spreadsheets.developerMetadata.get , указав идентификатор удаленных метаданных. Вы должны получить ответ с кодом состояния HTTP 404: Not Found с сообщением «Нет метаданных разработчика с идентификатором 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 . Вам нужно будет указать идентификатор таблицы и один или несколько фильтров данных, соответствующих метаданным.
Показать пример
В этом примере мы предоставляем идентификатор метаданных в запросе. Ответ возвращает значения ячеек строки (номер модели, ежемесячные продажи) для идентификатора метаданных.
Запрос
{
"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 . Вам нужно будет указать идентификатор таблицы и один или несколько фильтров данных, соответствующих метаданным.
Этот запрос функционирует как обычный запрос «GET электронной таблицы», за исключением того, что список метаданных, сопоставленных с указанными фильтрами данных, определяет, какие листы, данные сетки и другие ресурсы объекта с метаданными будут возвращены. Если для includeGridData установлено значение true, для листа также возвращаются данные сетки, пересекающие указанные диапазоны сетки.
Показать пример
В этом примере мы предоставляем идентификатор метаданных и устанавливаем для 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 . Вам потребуется указать идентификатор электронной таблицы, valueInputOption и один или несколько DataFilterValueRange , соответствующих метаданным.
Показать пример
В этом примере мы предоставляем идентификатор метаданных и обновленные значения строк в запросе. Ответ возвращает как обновленные свойства, так и данные для идентификатора метаданных.
Запрос
{
"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 . Вам нужно будет указать фильтр данных, чтобы выбрать метаданные, которые вы хотите очистить.
Показать пример
Запрос
В этом примере мы предоставляем идентификатор метаданных в запросе. Ответ возвращает идентификатор электронной таблицы и очищенные диапазоны.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}Ответ
{
"spreadsheetId": spreadsheetId,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}Ограничения на хранение метаданных
Существует ограничение на общий объем метаданных, которые вы можете хранить в электронной таблице. Этот предел измеряется в символах и состоит из двух компонентов:
| Элемент | Распределение лимита хранилища |
|---|---|
| электронная таблица | 30 000 символов |
| Каждый лист в электронной таблице | 30 000 символов |
В электронной таблице можно сохранить до 30 000 символов. Кроме того, вы можете хранить 30 000 символов для каждого листа электронной таблицы (30 000 для первого листа, 30 000 для второго листа и т. д.). Таким образом, электронная таблица из трех страниц может содержать до 120 000 символов метаданных разработчика.
Каждый символ в атрибутах ключа и значения объекта developerMetadata учитывается в этом пределе.