As máscaras de campo são uma maneira dos autores das chamadas da API listarem os campos que uma solicitação deve retornar ou atualizar. Ao usar um FieldMask permite que a API evite trabalhos desnecessários e melhora o desempenho. Uma máscara de campo é usado 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
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 melhores
desempenho,
listar explicitamente apenas os campos necessários
na resposta.
O formato do parâmetro "fields" é o mesmo que o Codificação JSON de uma FieldMask. Em resumo, campos diferentes são separados por vírgulas, e subcampos são separados por ponto. Os nomes dos campos podem ser especificados em camelCase ou separated_by_underscores. Para facilitar, vários subcampos do mesmo type pode ser listado entre parênteses.
Os seguintes presentations.get
exemplo de solicitação usa uma máscara de campo de
slides.pageElements(objectId,size,transform) para buscar apenas o ID do objeto,
Size e
transformar
de um pageElement
objeto 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 é uma
Objeto Presentation
contendo 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, você precisa atualizar apenas alguns campos em um objeto, deixando a
outros campos inalterados. Atualizar solicitações em um
presentations.batchUpdate
usam máscaras de campo para informar à API quais campos estão sendo alterados. A
de atualização ignora todos os campos que não são especificados na máscara de campo,
deixando-as com seus valores atuais.
Também é possível cancelar a definição de um campo não especificando-o na mensagem atualizada, mas adicionando o campo à máscara. Isso limpa o valor anterior do campo tinha.
A sintaxe das máscaras de campo de atualização é a mesma das máscaras de campo de leitura.
O exemplo a seguir usa
UpdateShapePropertiesRequest
para mudar o preenchimento de cor de uma forma para o tema DARK1 e cancelar a definição da
esboço:
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"
}
}
]
}