La función de metadatos del programador 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.
Los metadatos del programador te permiten realizar operaciones como las siguientes:
Asociar 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.Buscar todas las ubicaciones y los datos asociados con una clave o un atributo de metadatos en particular: Por ejemplo, si se proporciona la clave
totalsasociada con la columna D oresponseId, se muestran todas las filas con los metadatosresponseIdy el valor de metadatos asociado con ellos.Encontrar todos los datos asociados con una entidad o ubicación en particular: Por ejemplo, en el caso de la columna D, mostrar todos los metadatos asociados con esa ubicación.
Recuperar valores de una ubicación especificando los metadatos asociados: Por ejemplo, si se proporciona
totals, muestra una representación de los valores contenidos en la columna o fila asociada, o si se proporcionasummary, muestra una representación del recurso de hoja de cálculo asociado.Actualizar valores en una ubicación especificando metadatos asociados: Por ejemplo, en lugar de actualizar los valores de una fila a través de la notación A1, actualizar los valores indicando un ID de metadatos
Lee y escribe metadatos
El recurso spreadsheets.developerMetadata proporciona acceso a los metadatos del desarrollador asociados con una ubicación o un objeto en una hoja de cálculo.
Información acerca de los metadatos del desarrollador
En esta sección, se describen algunos aspectos clave de los metadatos del desarrollador que debes tener en cuenta cuando trabajas con la API de Hojas de cálculo.
Metadatos como etiquetas
Un uso de los metadatos del desarrollador es una etiqueta que asigna un nombre a una ubicación en la hoja de cálculo con solo una clave y una ubicación. Por ejemplo, puedes asociar headerRow con una fila en particular o totals con una columna en particular dentro de una hoja. Las etiquetas se pueden usar para vincular de manera semántica 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 afecten a tu app.
Metadatos como propiedades
Los metadatos creados mediante la especificación de una clave, una ubicación y un valor actúan como un par clave-valor asociado con esa ubicación en una hoja. Por ejemplo, puedes asociar lo siguiente:
formResponseId = resp123con una filalastUpdated = 1477369882con una columna
Esto te permite almacenar propiedades con nombres personalizados asociadas con áreas o datos en particular, y acceder a ellas, en una hoja de cálculo.
Diferencia entre los metadatos visibles del proyecto y del documento
Para evitar que un proyecto de desarrollador interfiera con los metadatos de otro, existen 2 parámetros de configuración de visibility de metadatos: project y document. Con la API de Hojas de cálculo, solo se pueden ver los metadatos del proyecto y acceder a ellos desde el proyecto de desarrollador que los creó. Se puede acceder a los metadatos del documento desde cualquier proyecto de desarrollador que tenga acceso al documento.
Las consultas que no especifican de manera explícita una visibilidad muestran metadatos de documentos y metadatos de proyectos que coinciden para el proyecto de desarrollador que realiza la solicitud.
Unicidad
No es necesario que las claves de metadatos sean únicas, pero el metadataId debe ser distinto. Si creas metadatos y dejas su campo de ID sin identificar, la API asigna uno. Este ID puede usarse para identificar los metadatos, mientras que las claves y otros atributos pueden usarse para identificar conjuntos de metadatos.
Crea metadatos
Para crear metadatos, usa el método batchUpdate y proporciona una createDeveloperMetadataRequest con un metadataKey, un location y un visibility. 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 realizará correctamente. Si no proporcionas un ID, la API te asignará uno.
Mostrar un ejemplo
En este ejemplo, proporcionamos una clave, un valor y una fila en la solicitud. La respuesta muestra estos valores de metadatos del desarrollador, además del ID de metadatos asignado.
Solicitud
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}Respuesta
{
"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"
}
}
}
]
}Lee un solo elemento de metadatos
Para obtener un único elemento de metadatos del desarrollador, usa el método spreadsheets.developerMetadata.get y especifica el spreadsheetId que contiene los metadatos y el metadataId único de los metadatos del desarrollador.
Mostrar un ejemplo
Solicitud
En este ejemplo, proporcionamos el ID de la hoja de cálculo y el ID de 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/spreadsheetId/developerMetadata/metadataId
Respuesta
{
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}Lee varios elementos de metadatos
Para recuperar varios elementos de metadatos del programador, usa el método spreadsheets.developerMetadata.search. Deberás especificar un DataFilter que coincida con cualquier metadato existente en cualquier combinación de propiedades, como clave, valor, ubicación o visibilidad.
Mostrar un ejemplo
En este ejemplo, proporcionamos varios IDs de metadatos en la solicitud. La respuesta muestra los valores de metadatos del desarrollador para cada ID de metadatos.
Solicitud
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
},
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}Respuesta
{
"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
}
}
]
}
]
}Actualizar metadatos
Para actualizar los metadatos del desarrollador, usa el método spreadsheets.batchUpdate y proporciona un UpdateDeveloperMetadataRequest.
Deberás especificar un DataFilter que apunte a los metadatos que se actualizarán, un objeto DeveloperMetadata con los valores nuevos y una máscara de campo que describa los campos que se actualizarán.
Mostrar un ejemplo
En este ejemplo, proporcionamos el ID de metadatos, el ID de hoja y una nueva clave de metadatos en la solicitud. La respuesta muestra estos valores de metadatos del desarrollador, además de la clave de metadatos actualizada.
Solicitud
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"developerMetadata": {
"location": {
"sheetId": sheetId
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}Respuesta
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Borra metadatos
Para borrar los metadatos del desarrollador, usa el método batchUpdate y proporciona una DeleteDeveloperMetadataRequest.
Deberás especificar un DataFilter para seleccionar los metadatos que desees borrar.
Mostrar un ejemplo
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 metadatos borrado. Deberías recibir una respuesta con el código de estado HTTP 404: Not Found, con el mensaje "No metadata del desarrollador con el ID metadataId".
Solicitud
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
}
}
}
]
}Respuesta
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Lee y escribe valores asociados con metadatos
También puedes recuperar y actualizar valores de celdas en filas y columnas especificando los metadatos del desarrollador asociados y los valores que deseas actualizar. Para ello, usa el método adecuado que se indica a continuación con un DataFilter que coincida.
Cómo obtener valores de celda a través de metadatos
Para obtener valores de celdas a través de metadatos, usa el método spreadsheets.values.batchGetByDataFilter. Deberás especificar el ID de la hoja de cálculo y uno o más filtros de datos que coincidan con los metadatos.
Mostrar un ejemplo
En este ejemplo, proporcionamos el ID de metadatos en la solicitud. La respuesta muestra los valores de las celdas de fila (número de modelo, ventas mensuales) para el ID de metadatos.
Solicitud
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"majorDimension": "ROWS"
}Respuesta
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}Cómo obtener una hoja de cálculo a través de metadatos
Cuando recuperas una hoja de cálculo, puedes mostrar un subconjunto de datos con el método spreadsheets.getByDataFilter. Deberás 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 “spreadsheet GET” normal, excepto que la lista de metadatos que coincide con los filtros de datos especificados determina las hojas, los datos de cuadrícula y otros recursos de objetos con metadatos que se muestran. Si includeGridData se establece como verdadero, los datos de cuadrícula con intersecciones en los rangos de cuadrícula especificados también se muestran para la hoja.
Mostrar un ejemplo
En este ejemplo, proporcionamos el ID de metadatos y establecemos includeGridData en false en la solicitud. La respuesta muestra las propiedades de la hoja de cálculo y de la hoja.
Solicitud
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"includeGridData": false
}Respuesta
{ "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 }
Actualiza valores a través de metadatos
Para actualizar los valores de las celdas que coincidan con metadatos específicos, usa el método spreadsheets.values.batchUpdateByDataFilter. Deberás especificar el ID de la hoja de cálculo, valueInputOption, y uno o más DataFilterValueRange que coincidan con los metadatos.
Mostrar un ejemplo
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 del ID de metadatos.
Solicitud
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}Respuesta
{
"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"
]
]
}
}
]
}Borrar valores por metadatos
Para borrar los valores de celdas que coincidan con metadatos específicos, usa el método spreadsheets.values.batchClearByDataFilter. Deberás especificar un filtro de datos para seleccionar los metadatos que deseas borrar.
Mostrar un ejemplo
Solicitud
En este ejemplo, proporcionamos el ID de metadatos en la solicitud. La respuesta muestra el ID de la hoja de cálculo y los rangos borrados.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}Respuesta
{
"spreadsheetId": spreadsheetId,
"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 tiene 2 componentes:
| Elemento | Asignación del límite de almacenamiento |
|---|---|
| Spreadsheet | 30,000 caracteres |
| Cada hoja de una hoja de cálculo | 30,000 caracteres |
Puedes almacenar hasta 30,000 caracteres por hoja de cálculo. Además, puedes almacenar 30,000 caracteres para cada hoja de una hoja de cálculo (30,000 para la hoja uno, 30,000 para la hoja 2, etcétera). Por lo tanto, una hoja de cálculo con 3 páginas podría contener hasta 120,000 caracteres de metadatos del desarrollador.
Cada carácter en los atributos clave y valor de un objeto developerMetadata cuenta para este límite.