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 Slides.

Ler com uma máscara de campo

As apresentações podem ser grandes, e muitas vezes você não precisa de todas as partes do recurso Presentation retornado por uma solicitação de leitura. É possível limitar o que é retornado em uma resposta da API Slides 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 presentations.get a seguir usa uma máscara de campo de slides.pageElements(objectId,size,transform) para buscar apenas o ID do objeto, Size e transformar um objeto pageElement em todos os slides de uma apresentação:

GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)

A resposta a essa chamada de método é um objeto Presentation que contém os componentes solicitados na máscara de campo:

{
  "slides": [
    {
      "pageElements": [
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311708,
            "translateY": 744575,
            "unit": "EMU"
          }
        },
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311700,
            "translateY": 2834125,
            "unit": "EMU"
          }
        }
     ]
    }
  ]
}

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 presentations.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 UpdateShapePropertiesRequest para mudar o preenchimento de cor de uma forma para a cor do tema DARK1 e redefinir o contorno da forma:

POST https://slides.googleapis.com/v1/presentations/presentationId:batchUpdate

{
  "requests": [
    {
      "updateShapeProperties": {
        "objectId": OBJECT_ID,
        "shapeProperties": {
          "shapeBackgroundFill": {
            "solidFill": {
              "color": {
                "themeColor": "DARK1"
              }
            }
          }
        },
        "fields": "shapeBackgroundFill.solidFill.color,outline"
      }
    }
  ]
}