O recurso de metadados do desenvolvedor permite associar metadados a várias entidades e locais em uma planilha. Em seguida, é possível consultar esses metadados e usá-los para encontrar os objetos associados a eles.
É possível associar metadados a linhas, colunas, páginas ou planilhas.
Os metadados do desenvolvedor permitem realizar operações como:
Associar dados arbitrários a várias entidades e locais em uma planilha. Por exemplo, associe
totalsà coluna D ouresponseId = 1234à linha 7.Encontrar todos os locais e dados associados a uma chave ou atributo de metadados específico. Por exemplo, com base na chave
totalsassociada à coluna D ou com aresponseId, retorne todas as linhas com os metadadosresponseIde o valor de metadados associado a elas.Encontrar todos os dados associados a uma determinada entidade ou local: por exemplo, com base na coluna D, retornar todos os metadados associados a esse local.
Recuperar valores em um local especificando metadados associados: por exemplo, com base em
totals, retorne uma representação dos valores contidos na coluna ou linha associada ou, com base emsummary, retorne uma representação do recurso de planilha associado.Atualizar valores em um local especificando metadados associados: por exemplo, em vez de atualizar os valores em uma linha usando a notação A1, atualize os valores indicando um ID de metadados.
Ler e gravar metadados
O recurso spreadsheets.developerMetadata fornece acesso aos metadados do desenvolvedor associados a um local ou objeto em uma planilha.
Sobre os metadados do desenvolvedor
Esta seção descreve alguns aspectos importantes dos metadados do desenvolvedor que você precisa considerar ao trabalhar com a API Sheets.
Metadados como tags
Um uso dos metadados do desenvolvedor é uma tag que nomeia um local na
planilha usando apenas uma chave e um local. Por
exemplo, é possível associar headerRow a uma linha específica ou totals a
uma coluna específica em uma página. As tags podem ser usadas para vincular semanticamente partes de uma
planilha a campos em uma ferramenta ou banco de dados de terceiros. Assim, as mudanças na
planilha não vão causar falhas no app.
Metadados como propriedades
Os metadados criados pela especificação de uma chave, um local e um valor atuam como um par chave-valor associado a esse local em uma planilha. Por exemplo, você pode associar:
formResponseId = resp123com uma linhalastUpdated = 1477369882com uma coluna.
Dessa forma, é possível armazenar e acessar propriedades nomeadas personalizadas associadas a determinadas áreas ou dados em uma planilha.
Metadados visíveis do projeto e do documento
Para evitar que um projeto de desenvolvedor interfira nos metadados de outro, há
duas configurações de visibility de metadados: project e document. Ao usar a API Sheets,
os metadados do projeto só podem ser vistos e acessados no projeto do desenvolvedor que
os criou. Os metadados do documento podem ser acessados em qualquer projeto de desenvolvedor com
acesso ao documento.
As consultas que não especificam explicitamente uma visibilidade retornam os metadados correspondentes do documento e do projeto do desenvolvedor que fez a solicitação.
Exclusividade
As chaves de metadados não precisam ser exclusivas, mas o metadataId precisa ser
diferente. Se você criar metadados e não especificar o campo de ID, a
API vai atribuir um. Esse ID pode ser usado para identificar os
metadados, enquanto chaves e outros atributos podem ser usados para identificar conjuntos de
metadados.
Criar metadados
Para criar metadados, use o método
batchUpdate
e forneça uma
createDeveloperMetadataRequest com um metadataKey, location e visibility. Opcionalmente,
especifique um metadataValue ou um metadataId explícito.
Se você especificar um ID que já está em uso, a solicitação não vai ser bem-sucedida. Se você não informar um ID, a API vai atribuir um.
Mostrar um exemplo
Neste exemplo, fornecemos uma chave, um valor e uma linha na solicitação. A resposta retorna esses valores de metadados do desenvolvedor, além do ID de metadados atribuído.
Solicitação
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}
Resposta
{
"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"
}
}
}
]
}
Ler um único item de metadados
Para recuperar um único metadado de desenvolvedor distinto, use o método
spreadsheets.developerMetadata.get,
especificando o spreadsheetId que contém os metadados e o metadataId exclusivo dos metadados do desenvolvedor.
Mostrar um exemplo
Solicitação
Neste exemplo, fornecemos o ID da planilha e o ID dos metadados na solicitação. A resposta retorna os valores de metadados do desenvolvedor para o ID de metadados.
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/developerMetadata/metadataId
Resposta
{
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}
Ler vários itens de metadados
Para recuperar vários itens de metadados de desenvolvedor, use o método
spreadsheets.developerMetadata.search. É necessário especificar um DataFilter que corresponda a metadados existentes em qualquer
combinação de propriedades, como chave, valor, local ou visibilidade.
Mostrar um exemplo
Neste exemplo, fornecemos vários IDs de metadados na solicitação. A resposta retorna os valores de metadados do desenvolvedor para cada ID de metadados.
Solicitação
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
},
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
Resposta
{
"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
}
}
]
}
]
}
Atualizar metadados
Para atualizar os metadados do desenvolvedor, use o método
spreadsheets.batchUpdate
e forneça um
UpdateDeveloperMetadataRequest.
É necessário especificar um
DataFilter
que identifique os metadados a serem atualizados, um objeto
DeveloperMetadata
com os novos valores e uma máscara de campo
que descreva os campos a serem atualizados.
Mostrar um exemplo
Neste exemplo, fornecemos o ID de metadados, o ID da planilha e uma nova chave de metadados na solicitação. A resposta retorna esses valores de metadados do desenvolvedor, além da chave de metadados atualizada.
Solicitação
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"developerMetadata": {
"location": {
"sheetId": sheetId
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}
Resposta
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}
Excluir metadados
Para excluir metadados do desenvolvedor, use o método
batchUpdate
e forneça uma
DeleteDeveloperMetadataRequest.
É necessário especificar um DataFilter para selecionar os metadados que você quer
excluir.
Mostrar um exemplo
Neste exemplo, fornecemos o ID de metadados na solicitação. A resposta retorna os valores de metadados do desenvolvedor para o ID de metadados.
Para confirmar que os metadados do desenvolvedor foram removidos, use o método spreadsheets.developerMetadata.get, especificando o ID de metadados excluído. Você vai receber uma resposta com o código de status HTTP 404: Not Found e uma mensagem informando que "Não há metadados do desenvolvedor com o ID metadataId.
Solicitação
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
}
}
}
]
}
Resposta
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}
Ler e gravar valores associados a metadados
Também é possível recuperar e atualizar valores de células em linhas e colunas especificando os metadados
do desenvolvedor associados e os valores que você quer atualizar. Para fazer isso, use o método apropriado abaixo com um
DataFilter correspondente.
Receber valores de células por metadados
Para receber valores de célula por metadados, use o método spreadsheets.values.batchGetByDataFilter. Você precisa especificar o ID da planilha e um ou mais filtros de dados que correspondam aos metadados.
Mostrar um exemplo
Neste exemplo, fornecemos o ID de metadados na solicitação. A resposta retorna os valores da célula da linha (número do modelo, vendas mensais) para o ID de metadados.
Solicitação
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"majorDimension": "ROWS"
}
Resposta
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}
Receber planilha por metadados
Ao extrair uma planilha, você pode retornar um subconjunto de dados usando o método spreadsheets.getByDataFilter. Você precisa especificar o ID da planilha e um ou mais filtros de dados que correspondam aos metadados.
Essa solicitação funciona como uma solicitação "spreadsheet GET" normal, exceto que a
lista de metadados correspondida pelos filtros de dados especificados determina quais folhas, dados de grade e outros recursos de objeto com metadados são retornados. Se
includeGridData for definido como verdadeiro, os dados de grade que fazem interseção com os intervalos de grade especificados
também serão retornados para a planilha.
Mostrar um exemplo
Neste exemplo, fornecemos o ID de metadados e definimos "includeGridData" como "false" na solicitação. A resposta retorna as propriedades da planilha e da página.
Solicitação
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"includeGridData": false
}
Resposta
{
"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
}
Atualizar valores por metadados
Para atualizar os valores de células que correspondem a metadados específicos, use o método
spreadsheets.values.batchUpdateByDataFilter. É necessário especificar o ID da planilha, valueInputOption, e uma ou mais DataFilterValueRange que correspondam aos metadados.
Mostrar um exemplo
Neste exemplo, fornecemos o ID de metadados e os valores de linha atualizados na solicitação. A resposta retorna as propriedades e os dados atualizados do ID de metadados.
Solicitação
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}
Resposta
{
"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"
]
]
}
}
]
}
Limpar valores por metadados
Para limpar valores de células que correspondem a metadados específicos, use o método spreadsheets.values.batchClearByDataFilter. É necessário especificar um filtro de dados para selecionar os metadados que você quer limpar.
Mostrar um exemplo
Solicitação
Neste exemplo, fornecemos o ID de metadados na solicitação. A resposta retorna o ID da planilha e os intervalos limpos.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
Resposta
{
"spreadsheetId": spreadsheetId,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}
Limites de armazenamento de metadados
Há um limite para a quantidade total de metadados que pode ser armazenada em uma planilha. Esse limite é medido em caracteres e é derivado de dois componentes:
| Item | Alocação do limite de armazenamento |
|---|---|
| Planilha | 30.000 caracteres |
| Cada página em uma planilha | 30.000 caracteres |
É possível armazenar até 30.000 caracteres na planilha. Além disso, é possível armazenar 30.000 caracteres para cada página de uma planilha (30.000 para a página 1, 30.000 para a página 2 e assim por diante). Portanto,uma planilha com três páginas pode conter até 120.000 caracteres de metadados de desenvolvedor.
Cada caractere nos atributos de chave e valor de um objeto developerMetadata
é considerado nesse limite.