Las máscaras de campo permiten que los llamadores de la API enumeren los campos que una solicitud debe mostrar o actualizar. El uso de FieldMask permite que la API evite el trabajo innecesario y mejora el rendimiento. Se usa una máscara de campo para los métodos de lectura y actualización en la API de Hojas de cálculo de Google.
Lee con una máscara de campo
Las hojas de cálculo pueden ser grandes y, a menudo, no es necesario que todas las partes del recurso Spreadsheet devuelvan por una solicitud de lectura. Puedes limitar lo que se muestra en una respuesta de la API de Hojas de cálculo con el parámetro de URL fields. Para obtener el mejor rendimiento, enumera de forma explícita solo los campos que necesitas en la respuesta.
El formato del parámetro de los campos es el mismo que la codificación JSON de una FieldMask. En pocas palabras, varios campos diferentes están separados por comas y los subcampos están separados por puntos. Los nombres de los campos se pueden especificar con el formato camelCase o separados_por_guiones bajos. Para mayor comodidad, varios subcampos del mismo tipo pueden enumerarse entre paréntesis.
En el siguiente ejemplo de solicitud spreadsheets.get, se usa una máscara de campo sheets.properties(sheetId,title,sheetType,gridProperties) para recuperar solo el ID de la hoja, el título, SheetType y GridProperties de un objeto SheetProperties en todas las hojas de una hoja de cálculo:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)
La respuesta a este método es un objeto Spreadsheet que contiene los componentes solicitados en la máscara de campo. Ten en cuenta que sheetType=OBJECT no contiene gridProperties:
{
"sheets": [
{
"properties": {
"sheetId": SHEET_ID,
"title": "TITLE",
"sheetType": "GRID",
"gridProperties": {
"rowCount": 1000,
"columnCount": 25
}
}
},
{
"properties": {
"sheetId": SHEET_ID,
"title": "TITLE",
"sheetType": "OBJECT"
}
}
]
}
Actualizar con una máscara de campo
A veces, solo debes actualizar ciertos campos de un objeto y no modificar los demás. Las solicitudes de actualización dentro de una operación spreadsheets.batchUpdate usan máscaras de campo para indicarle a la API qué campos se cambiarán. La solicitud de actualización ignora los campos que no se especifican en la máscara de campo, lo que les deja sus valores actuales.
También puedes dejar de configurar un campo si no lo especificas en el mensaje actualizado, sino que lo agregas a la máscara. Esto borra cualquier valor que el campo tenía antes.
La sintaxis de las máscaras de campo de actualización es la misma que la de las máscaras de campo de lectura.
En el siguiente ejemplo, se usa AddSheetRequest para agregar una hoja nueva de tipo Grid, inmovilizar la primera fila y cambiar el color de la pestaña de la hoja nueva de rojo:
POST https://sheets.googleapis.com/v1/spreadsheets/spreadsheetId:batchUpdate
{
"spreadsheetId": "SPREADSHEET_ID",
"replies": [
{
"addSheet": {
"properties": {
"sheetId": SHEET_ID,
"title": "TITLE",
"index": 6,
"sheetType": "GRID",
"gridProperties": {
"rowCount": 1000,
"columnCount": 26,
"frozenRowCount": 1
},
"tabColor": {
"red": 0.003921569
},
"tabColorStyle": {
"rgbColor": {
"red": 0.003921569
}
}
}
}
}
]
}