Las máscaras de campo son una forma para que los emisores de la API enumeren los campos que una solicitud debe mostrar o actualizar. El uso de un FieldMask permite que la API evite el trabajo innecesario y mejore 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 necesitas todas las partes del recurso Spreadsheet
que muestra 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 campos es el mismo que la codificación JSON de un FieldMask. En resumen, varios campos diferentes se separan por comas y los subcampos se separan por puntos. Los nombres de los campos se pueden especificar en mayúsculas y minúsculas o separados por guiones bajos. Para mayor comodidad, se pueden enumerar varios subcampos del mismo tipo entre paréntesis.
En el siguiente ejemplo de solicitud spreadsheets.get
, se usa una máscara de campo de 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 esta llamada de 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" } } ] }
Actualiza con una máscara de campo
A veces, solo necesitas actualizar ciertos campos de un objeto y dejar los otros sin cambios. 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 están cambiando. La solicitud de actualización ignora los campos que no se especifican en la máscara de campo, y los deja con sus valores actuales.
También puedes restablecer un campo si no lo especificas en el mensaje actualizado, pero lo agregas a la máscara. Esto borra cualquier valor que el campo tenía anteriormente.
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 colorear de rojo la pestaña de la hoja nueva:
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 } } } } } ] }