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 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 extrair o melhor
desempenho possível,
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 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 esta 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 de um objeto e deixar
os outros como estão. 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 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.
O exemplo a seguir usa o
UpdateShapePropertiesRequest
para mudar a cor de preenchimento de uma forma para a cor do tema DARK1 e remover a definição do
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"
}
}
]
}