As máscaras de campo são uma maneira dos autores de chamada da API listarem os campos que uma solicitação precisa retornar ou atualizar. O uso de FieldMask permite que a API evite trabalhos desnecessários e melhore o desempenho. Uma máscara de campo é usada para os 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
retornados por uma solicitação de leitura. Você pode limitar o que é retornado em uma resposta da API Slides 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 "fields" é o mesmo da codificação JSON de um FieldMask. Em resumo, vários campos diferentes são separados por vírgulas e os subcampos são separados por pontos. É possível especificar os nomes dos campos em camelCase ou Separate_by_underscores. Por 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
de 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, é preciso atualizar apenas alguns campos em um objeto, deixando os outros inalterados. As solicitações de atualização dentro de 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 os campos que não estão especificados na máscara de campo, mantendo os valores atuais.
Também é possível cancelar a definição de um campo não especificando 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 desativar 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"
}
}
]
}