Le maschere di campo consentono agli utenti che chiamano l'API di elencare i campi che una richiesta deve restituire o aggiornare. L'utilizzo di un FieldMask consente all'API di evitare operazioni non necessarie e migliora le prestazioni. Una maschera di campo viene utilizzata sia per i metodi di lettura che di aggiornamento nell'API Google Presentazioni.
Per un confronto tra ciò che viene restituito nel corpo di una risposta quando non utilizzi una maschera di campo e quando la utilizzi, consulta Utilizzare risorse parziali.
Lettura con una maschera di campo
Le presentazioni possono essere di grandi dimensioni e spesso non è necessaria ogni parte della risorsa
presentations
restaurata da una richiesta di lettura. Puoi limitare i dati restituiti in una risposta dell'API di Presentazioni utilizzando il parametro URL fields. Per ottenere il miglior
rendimento, elenca esplicitamente solo i campi di cui hai bisogno nella risposta.
Il formato del parametro fields è lo stesso della codifica JSON di un FieldMask. In breve, più campi diversi sono separati da virgole e i sottocampi da punti. I nomi di campo possono essere specificati in camelCase o separated_by_underscores. Per praticità, è possibile elencare più campi secondari dello stesso tipo tra parentesi.
Il seguente
presentations.get
esempio di richiesta del metodo utilizza una maschera di campo di
slides.pageElements(objectId,size,transform) per recuperare solo l'ID oggetto,
Size e
trasforma
di un
pageElement
oggetto in tutte le diapositive di una presentazione:
GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)
La risposta a questa chiamata di metodo è un oggetto
presentations contenente i componenti richiesti nella maschera di 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"
}
}
]
}
]
}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 metodo
presentations.batchUpdate
utilizzano le maschere di campo per indicare all'API quali campi vengono modificati. La richiesta di aggiornamento ignora i campi non specificati nella maschera di campi, lasciandoli con i valori correnti.
Puoi anche annullare l'impostazione di un campo non specificandolo nel messaggio aggiornato, ma aggiungendolo alla maschera. In questo modo viene cancellato il valore precedentemente associato al campo.
La sintassi delle maschere dei campi di aggiornamento è la stessa delle maschere dei campi di lettura.
L'esempio seguente utilizza il metodo
UpdateShapePropertiesRequest
per modificare il colore di riempimento di una forma con il colore del tema DARK1 e annullare l'impostazione del contorni 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"
}
}
]
}