As máscaras de campo são uma maneira dos autores da chamada de API listarem os campos que uma solicitação precisa retornar ou atualizar. O uso de um FieldMask permite que a API evite trabalho desnecessário e melhora o desempenho. Uma máscara de campo é usada para os métodos de leitura e atualização na API Google Sheets.
Ler com uma máscara de campo
As planilhas podem ser grandes e, muitas vezes, você não precisa de todas as partes do
recurso Spreadsheet
retornado por uma solicitação de leitura. Você pode limitar o que é retornado em uma resposta da API Sheets usando o parâmetro de URL fields. Para ter o melhor
desempenho,
liste explicitamente apenas os campos necessários
na resposta.
O formato do parâmetro "fields" é igual à codificação JSON de um FieldMask. Em resumo, vários campos diferentes são separados por vírgulas e os subcampos são separados por pontos. Os nomes dos campos podem ser especificados em camelCase ou Separate_by_underscores. Por conveniência, vários subcampos do mesmo tipo podem ser listados entre parênteses.
O exemplo de solicitação spreadsheets.get a seguir usa uma máscara de campo de sheets.properties(sheetId,title,sheetType,gridProperties) para buscar apenas o ID, título, SheetType e GridProperties da planilha de um objeto SheetProperties em todas as páginas de uma planilha:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)
A resposta a essa chamada de método é um objeto
Spreadsheet
que contém os componentes solicitados na máscara de campo. Observe que
sheetType=OBJECT não contém gridProperties:
{
"sheets": [
{
"properties": {
"sheetId": SHEET_ID,
"title": "TITLE",
"sheetType": "GRID",
"gridProperties": {
"rowCount": 1000,
"columnCount": 25
}
}
},
{
"properties": {
"sheetId": SHEET_ID,
"title": "TITLE",
"sheetType": "OBJECT"
}
}
]
}
Atualizar com uma máscara de campo
Às vezes, é necessário atualizar apenas alguns campos de um objeto e deixar os
outros inalterados. As solicitações de atualização dentro de uma operação spreadsheets.batchUpdate usam máscaras de campo para informar à API quais campos estão sendo alterados. A
solicitação de atualização ignora todos os campos que não estejam especificados na máscara de campo,
deixando-os com os valores atuais.
Também é possível cancelar a definição de um campo não especificando-o na mensagem atualizada, mas adicionando o campo à máscara. Isso limpa qualquer valor que o campo tinha anteriormente.
A sintaxe das máscaras de campo de atualização é a mesma que a das máscaras de campo de leitura.
O exemplo a seguir usa o AddSheetRequest para adicionar uma nova página do tipo Grid, congelar a primeira linha e colorir a guia da nova planilha de vermelho:
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
}
}
}
}
}
]
}