La función de metadatos te permite asociar metadatos con varias entidades y ubicaciones en una hoja de cálculo. Luego, puedes consultar estos metadatos y usarlos para encontrar los objetos con los que están asociados.
Puedes asociar metadatos con filas, columnas, hojas o una hoja de cálculo.
Puedes generar metadatos para realizar operaciones como las siguientes:
Asocia datos arbitrarios con varias entidades y ubicaciones en una hoja de cálculo: Por ejemplo, asocia
totalscon la columna D oresponseId = 1234con la fila 7.Encuentra todas las ubicaciones y los datos asociados con una clave o un atributo de metadatos en particular: Por ejemplo, dada la clave
totalsasociada con la columna D o dado elresponseId, devuelve todas las filas con los metadatos deresponseIdy el valor de metadatos asociado con ellos.Encuentra todos los datos asociados a una entidad o ubicación en particular: Por ejemplo, dada la columna D, devuelve todos los metadatos asociados a esa ubicación.
Recupera valores en una ubicación especificando metadatos asociados: Por ejemplo, dado el
totals, devuelve una representación de los valores contenidos en la columna o fila asociada, o bien, dado unsummary, devuelve una representación del recurso de la hoja asociado.Actualiza los valores en una ubicación especificando los metadatos asociados: Por ejemplo, en lugar de actualizar los valores en una fila a través de la notación A1, actualiza los valores indicando un ID de metadatos.
Leer y escribir metadatos
El recurso spreadsheets.developerMetadata proporciona acceso a los metadatos asociados con una ubicación o un objeto en una hoja de cálculo.
Acerca de los metadatos
En esta sección, se describen algunos aspectos clave de los metadatos que debes tener en cuenta cuando trabajes con la API de Sheets.
Metadatos como etiquetas: Un uso de los metadatos del desarrollador es una etiqueta que nombra una ubicación en la hoja de cálculo usando solo una clave y una ubicación. Por ejemplo, puedes asociar
headerRowcon una fila en particular ototalscon una columna en particular dentro de una hoja. Las etiquetas se pueden usar para vincular semánticamente partes de una hoja de cálculo a campos en una herramienta o base de datos de terceros, de modo que los cambios en la hoja de cálculo no interrumpan tu app.Metadatos como propiedades: Son metadatos que se crean especificando una clave, una ubicación y un valor que actúa como un par clave-valor asociado a esa ubicación en una hoja. Por ejemplo, puedes asociar lo siguiente:
formResponseId = resp123con una filalastUpdated = 1477369882con una columna
Esto te permite almacenar y acceder a propiedades con nombre personalizadas asociadas con áreas o datos particulares en una hoja de cálculo.
Metadatos visibles del proyecto y del documento: Para evitar que un proyecto de desarrollador interfiera en los metadatos de otro, hay dos parámetros de configuración de metadatos:
projectydocument.visibilityCon la API de Sheets, los metadatos del proyecto solo son visibles y accesibles desde el proyecto de Google Cloud que los creó. Se puede acceder a los metadatos del documento desde cualquier proyecto de Google Cloud que tenga acceso al documento.Las búsquedas que no especifican de forma explícita una visibilidad devuelven metadatos de documentos y metadatos de proyectos coincidentes para el proyecto de Google Cloud que realiza la solicitud.
Unicidad: Las claves de metadatos no tienen que ser únicas, pero el
metadataIddebe ser distinto. Si creas metadatos y dejas sin especificar su campo de ID, la API asigna uno. Este ID se puede usar para identificar los metadatos, mientras que las claves y otros atributos se pueden usar para identificar conjuntos de metadatos.
Crea metadatos
Para crear metadatos, usa el método batchUpdate en el recurso spreadsheets y proporciona un CreateDeveloperMetadataRequest con los valores metadataKey, location y visibility del recurso spreadsheets.developerMetadata. De manera opcional, puedes especificar un metadataValue o un metadataId explícito.
Si especificas un ID que ya está en uso, la solicitud no se completará. Si no proporcionas un ID, la API asignará uno.
En este ejemplo, proporcionamos una clave, un valor y una fila en la solicitud. La respuesta devuelve estos valores de metadatos para desarrolladores, además del ID de metadatos asignado.
Solicitud
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}Respuesta
{
"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"
}
}
}
]
}Lee un solo elemento de metadatos
Para recuperar un solo metadato para desarrolladores distinto, usa el método spreadsheets.developerMetadata.get y especifica el spreadsheetId que contiene los metadatos y el metadataId único de los metadatos para desarrolladores.
Solicitud
En este ejemplo, proporcionamos el ID de la hoja de cálculo y el ID de los metadatos en la solicitud. La respuesta muestra los valores de metadatos del desarrollador para el ID de metadatos.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/developerMetadata/METADATA_ID
Respuesta
{
"metadataId": METADATA_ID,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}Lee varios elementos de metadatos
Para recuperar varios elementos de metadatos para desarrolladores, usa el método spreadsheets.developerMetadata.search. Debes especificar un DataFilter que coincida con los metadatos existentes en cualquier combinación de propiedades, como clave, valor, ubicación o visibilidad.
En este ejemplo, proporcionamos varios IDs de metadatos en la solicitud. La respuesta devuelve los valores de metadatos del desarrollador para cada ID de metadatos.
Solicitud
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}Respuesta
{
"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
}
}
]
}
]
}Actualizar metadatos
Para actualizar los metadatos del desarrollador, usa el método spreadsheets.batchUpdate y proporciona un UpdateDeveloperMetadataRequest.
Debes especificar un DataFilter que segmenta los metadatos que se actualizarán, un recurso spreadsheets.developerMetadata con los valores nuevos y una máscara de campo que describa los campos que se actualizarán.
En este ejemplo, proporcionamos el ID de metadatos, el ID de hoja y una nueva clave de metadatos en la solicitud. La respuesta devuelve estos valores de metadatos para desarrolladores, además de la clave de metadatos actualizada.
Solicitud
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"developerMetadata": {
"location": {
"sheetId": SHEET_ID
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}Respuesta
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": METADATA_ID,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Borra metadatos
Para borrar metadatos del desarrollador, usa el método batchUpdate y proporciona un DeleteDeveloperMetadataRequest.
Debes especificar un DataFilter para seleccionar los metadatos que deseas borrar.
En este ejemplo, proporcionamos el ID de metadatos en la solicitud. La respuesta muestra los valores de metadatos del desarrollador para el ID de metadatos.
Para confirmar que se quitaron los metadatos del desarrollador, usa el método spreadsheets.developerMetadata.get y especifica el ID de los metadatos borrados. Deberías recibir una respuesta con el código de estado HTTP 404: Not Found y un mensaje que indique "No hay metadatos del desarrollador con el ID METADATA_ID".
Solicitud
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
}
}
]
}Respuesta
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": METADATA_ID,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Leer y escribir valores asociados con metadatos
También puedes recuperar y actualizar los valores de las celdas en filas y columnas especificando los metadatos para desarrolladores asociados y los valores que deseas actualizar. Para ello, usa uno de los siguientes métodos con un DataFilter coincidente.
Obtén valores de celdas por metadatos
Para obtener valores de celdas por metadatos, usa el método spreadsheets.values.batchGetByDataFilter. Debes especificar el ID de la hoja de cálculo y uno o más filtros de datos que coincidan con los metadatos.
En este ejemplo, proporcionamos el ID de metadatos en la solicitud. La respuesta devuelve los valores de las celdas de la fila (número de modelo, ventas mensuales) para el ID de metadatos.
Solicitud
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"majorDimension": "ROWS"
}Respuesta
{
"spreadsheetId": SPREADSHEET_ID,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}
]
}Obtén una hoja de cálculo por metadatos
Cuando recuperas una hoja de cálculo, puedes devolver un subconjunto de datos con el método spreadsheets.getByDataFilter. Debes especificar el ID de la hoja de cálculo y uno o más filtros de datos que coincidan con los metadatos.
Esta solicitud funciona como una solicitud normal de "GET de hoja de cálculo", excepto que la lista de metadatos que coinciden con los filtros de datos especificados determina qué hojas, datos de cuadrícula y otros recursos de objetos con metadatos se devuelven. Si includeGridData se establece como verdadero, también se devuelven los datos de cuadrícula que se cruzan con los rangos de cuadrícula especificados para la hoja. El campo includeGridData se ignora si se establece una máscara de campo en la solicitud.
En este ejemplo, proporcionamos el ID de metadatos y establecemos includeGridData como falso en la solicitud. La respuesta devuelve las propiedades de la hoja de cálculo y de la hoja.
Solicitud
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"includeGridData": false
}Respuesta
{ "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 }
Actualiza los valores por metadatos
Para actualizar los valores de las celdas que coinciden con metadatos específicos, usa el método spreadsheets.values.batchUpdateByDataFilter. Debes especificar el ID de la hoja de cálculo, valueInputOption, y uno o más valores de DataFilterValueRange que coincidan con los metadatos.
En este ejemplo, proporcionamos el ID de metadatos y los valores de fila actualizados en la solicitud. La respuesta muestra las propiedades y los datos actualizados para el ID de metadatos.
Solicitud
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}Respuesta
{
"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"
]
]
}
}
]
}Borra los valores por metadatos
Para borrar los valores de las celdas que coinciden con metadatos específicos, usa el método spreadsheets.values.batchClearByDataFilter. Debes especificar un filtro de datos para seleccionar los metadatos que deseas borrar.
Solicitud
En este ejemplo, proporcionamos el ID de metadatos en la solicitud. La respuesta devuelve el ID de la hoja de cálculo y los rangos borrados.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}Respuesta
{
"spreadsheetId": SPREADSHEET_ID,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}Límites de almacenamiento de metadatos
Existe un límite para la cantidad total de metadatos que puedes almacenar en una hoja de cálculo. Este límite se mide en caracteres y consta de dos componentes:
| Elemento | Asignación del límite de almacenamiento |
|---|---|
| Hoja de cálculo | 30,000 caracteres |
| Cada hoja de una hoja de cálculo | 30,000 caracteres |
Puedes almacenar hasta 30,000 caracteres en la hoja de cálculo. Además, puedes almacenar 30,000 caracteres en cada hoja de cálculo (30,000 en la hoja uno, 30,000 en la hoja dos, y así sucesivamente). Por lo tanto, una hoja de cálculo con tres hojas podría contener hasta 120,000 caracteres de metadatos.
Cada carácter de los campos metadataKey y metadataValue del recurso spreadsheets.developerMetadata se incluye en este límite.