Le maschere di campo consentono ai chiamanti API di elencare i campi che una richiesta dovrebbe restituire o aggiornare. L'utilizzo di una FieldMask consente all'API di evitare lavoro non necessario e migliora le prestazioni. Una maschera di campo viene utilizzata sia per i metodi di lettura che per quelli di aggiornamento nell'API Presentazioni Google.
Lettura con una maschera dei campi
Le presentazioni possono essere di grandi dimensioni e spesso non è necessario che ogni parte della risorsa Presentation venga restituita da una richiesta di lettura. Puoi limitare ciò che viene restituito in una risposta dell'API Presentazioni utilizzando il parametro URL fields. Per ottenere le migliori prestazioni, elenca esplicitamente solo i campi necessari nella risposta.
Il formato del parametro dei campi è lo stesso della codifica JSON di una maschera di campo. In breve, più campi diversi sono separati da virgole, mentre i campi secondari sono separati da punti. I nomi dei campi possono essere specificati in camelCase o separate_by_underscores. Per praticità, tra parentesi possono essere elencati più sottocampi dello stesso tipo.
Il seguente esempio di richiesta presentations.get utilizza la maschera del campo slides.pageElements(objectId,size,transform) per recuperare solo l'ID oggetto Size e la trasformazione di un oggetto pageElement su tutte le slide di una presentazione:
GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)
La risposta a questa chiamata al metodo è un oggetto Presentation contenente i componenti richiesti nella maschera dei campi:
{
"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"
}
}
]
}
]
}
Aggiornamento con una maschera dei campi
A volte è necessario aggiornare solo alcuni campi di un oggetto, lasciando invariati gli altri. Le richieste di aggiornamento all'interno di un'operazione presentations.batchUpdate utilizzano le maschere dei campi per indicare all'API quali campi vengono modificati. La richiesta di aggiornamento ignora i campi non specificati nella maschera dei campi, lasciandoli con i valori attuali.
Puoi anche annullare l'impostazione di un campo non specificandolo nel messaggio aggiornato, ma aggiungendolo alla maschera. In questo modo viene cancellato qualsiasi valore assegnato in precedenza al campo.
La sintassi per le maschere dei campi di aggiornamento è la stessa delle maschere dei campi di lettura.
Nell'esempio seguente viene utilizzato UpdateShapePropertiesRequest per modificare il riempimento del colore di una forma con il colore del tema DARK1 e annullare l'impostazione del contorno della 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"
}
}
]
}