Usar máscaras de campo

Máscaras de campo são uma forma de os autores da chamada à API listarem os campos que uma solicitação precisa retornar ou atualizar. O uso de uma FieldMask permite que a API evite trabalho desnecessário e melhore a performance. 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. É possível 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 de campos é igual à codificação JSON de uma FieldMask. Em resumo, campos diferentes são separados por vírgulas e subcampos são separados por pontos. Os nomes dos campos podem ser especificados em camelCase ou separated_by_underscores. Para fins de 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 extrair apenas o ID da página, o título, SheetType e GridProperties 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 esta chamada de método é um objeto Spreadsheet que contém os componentes solicitados na máscara de campo. 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, é preciso atualizar apenas alguns campos de um objeto e deixar os outros como estão. 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 estiverem especificados na máscara de campo, deixando-os com os valores atuais.

Você também pode não definir um campo removendo a definição dele na mensagem atualizada, mas adicionando-o à máscara. Isso apaga qualquer valor que o campo tinha anteriormente.

A sintaxe das máscaras de campo de atualização é a mesma que a usada para as máscaras de campo de leitura.

Uma máscara de campo de * é tratada como um caractere curinga e é abreviada para especificar todos os campos em uma mensagem. A sintaxe de caractere curinga pode produzir resultados indesejados se a API for atualizada no futuro, já que os campos somente leitura e os recém-adicionados podem causar erros. Para aplicativos de produção, sempre liste os campos específicos sendo atualizados nas máscaras de campo e evite usar caracteres curinga *.

O exemplo a seguir usa o AddSheetRequest para adicionar uma nova planilha 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
            }
          }
        }
      }
    }
  ]
}