Usar máscaras de campo

As máscaras de campo são uma maneira de os autores de chamadas de API listar os campos que uma solicitação precisa retornar ou atualizar. O uso de uma FieldMask permite que a API evite trabalhos desnecessários e melhore a performance. Uma máscara de campo é usada nos 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 melhor desempenho, liste explicitamente apenas os campos necessários na resposta.

O formato do parâmetro fields é igual à codificação JSON de um FieldMask. Resumidamente, 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 separated_by_underscores. Para sua conveniência, vários subcampos do mesmo tipo podem ser listados entre parênteses.

O exemplo de solicitação spreadsheets.get abaixo usa uma máscara de campo de sheets.properties(sheetId,title,sheetType,gridProperties) para buscar apenas o ID, o título, SheetType e GridProperties de um objeto SheetProperties em todas as planilhas 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 determinados campos em um objeto e deixar os outros campos inalterados. As solicitações de atualização em 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 são especificados na máscara de campo, deixando-os com os valores atuais.

Também é possível redefinir um campo sem especificá-lo 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 das máscaras de campo de leitura.

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
            }
          }
        }
      }
    }
  ]
}