As máscaras de campo são uma maneira dos autores das chamadas da API listarem os campos que uma solicitação deve retornar ou atualizar. Ao usar um FieldMask permite que a API evite trabalhos desnecessários e melhora o desempenho. Uma máscara de campo é usado 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
Spreadsheet
é retornado por uma solicitação de leitura. É possível limitar o que é retornado em uma
Resposta da API Sheets, usando o parâmetro de URL fields. Para melhores
desempenho,
listar explicitamente apenas os campos necessários
na resposta.
O formato do parâmetro "fields" é o mesmo que o Codificação JSON de uma FieldMask. Em resumo, campos diferentes são separados por vírgulas, e subcampos são separados por ponto. Os nomes dos campos podem ser especificados em camelCase ou separated_by_underscores. Para facilitar, vários subcampos do mesmo type pode ser listado entre parênteses.
O seguinte
Solicitação spreadsheets.get
usa uma máscara de campo de sheets.properties(sheetId,title,sheetType,gridProperties) para
buscar apenas o ID da planilha, o título,
SheetType e
GridProperties
de um
SheetProperties
objeto 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 é uma
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, você precisa atualizar apenas alguns campos em um objeto, deixando a
outros campos inalterados. Atualizar solicitações em um
spreadsheets.batchUpdate
usam máscaras de campo para informar à API quais campos estão sendo alterados. A
de atualização ignora todos os campos que não são especificados na máscara de campo,
deixando-as com seus 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 o valor anterior do campo tinha.
A sintaxe das máscaras de campo de atualização é a mesma das máscaras de campo de leitura.
O exemplo a seguir usa
AddSheetRequest
para adicionar uma nova folha do tipo Grid, congelar a primeira linha e colorir a nova
guia da página em 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
}
}
}
}
}
]
}