Usar máscaras de campo

As máscaras de campo são uma maneira de os autores de chamadas de API listarem 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 para os métodos de leitura e atualização na API Google Slides.

Para uma comparação do que é retornado em um corpo de resposta quando você não usa uma máscara de campo e quando usa, consulte Trabalhar com recursos parciais.

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 presentations recurso 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 performance, liste explicitamente apenas os campos necessários na resposta .

O formato do parâmetro de campos é o mesmo da codificação JSON de uma 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 separados_por_sublinhados. Para sua conveniência, vários subcampos do mesmo tipo podem ser listados entre parênteses.

O exemplo de solicitação de método a seguir usa uma máscara de campo de slides.pageElements(objectId,size,transform) para buscar apenas o ID do objeto, Size, e transformação de um objeto pageElement em todos os slides de uma apresentação:presentations.get

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

A resposta a essa chamada de método é um presentations objeto 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 manter os outros inalterados. As solicitações de atualização em um presentations.batchUpdate método 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 seus valores atuais.

Também é possível remover a definição de 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 método para mudar o preenchimento de cor de uma forma para a cor do tema DARK1 e remover 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"
      }
    }
  ]
}