Le maschere di campo consentono ai chiamanti API di elencare i campi che una richiesta deve restituire o aggiornare. L'utilizzo di una FieldMask consente all'API di evitare il lavoro non necessario e migliora le prestazioni. Viene utilizzata una maschera di campo per entrambi i metodi di lettura e aggiornamento nell'API Documenti Google.
Lettura con una maschera del campo
I documenti possono essere di grandi dimensioni e spesso non è necessaria ogni parte della risorsa Document restituita da una richiesta di lettura. Puoi limitare ciò che viene restituito in una risposta dell'API Documenti utilizzando il parametro URL fields. Per ottenere prestazioni ottimali, elenca esplicitamente solo i campi necessari nella risposta.
Il formato del parametro dei campi è lo stesso della codifica JSON di una maschera per i campi. In breve, i vari campi sono separati da virgole e i sottocampi sono separati da punti. I nomi dei campi possono essere specificati in camelCase o separate_by_underscores. Per praticità, più sottocampi dello stesso tipo possono essere elencati tra parentesi.
Il seguente esempio di richiesta documents.get utilizza una maschera di campo title,body.content(paragraph),revisionId per recuperare title del documento, Paragraph di un oggetto Body e revisionId del documento all'interno di un documento:
GET https://docs.googleapis.com/v1/documents/documentId?fields=title,body.content(paragraph),revisionId
La risposta a questa chiamata al metodo è un oggetto Document contenente i componenti richiesti nella maschera del campo:
{
"title": ""TITLE",
"body": {
"content": [
{},
{
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 59,
"textRun": {
"content": ""CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
},
"revisionId": "REVISION_ID"
}
Aggiorna con una maschera del campo
A volte è necessario aggiornare solo alcuni campi di un oggetto, lasciando invariati gli altri. Le richieste di aggiornamento all'interno di un'operazione documents.batchUpdate utilizzano le maschere dei campi per indicare all'API quali campi vengono modificati. La richiesta di aggiornamento ignora tutti i campi non specificati nella maschera del campo, 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 qualsiasi valore che il campo aveva precedentemente.
La sintassi per le maschere del campo di aggiornamento è la stessa delle maschere dei campi di lettura.
L'esempio seguente utilizza UpdateTextStyleRequest per definire lo stile delle parole "API Documenti Google" nel documento in grassetto all'interno dell'intervallo range 5-20:
POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{
"title": "TITLE",
"body": {
"content": [
{
"endIndex": 1,
"sectionBreak": {
"sectionStyle": {
"columnSeparatorStyle": "NONE",
"contentDirection": "LEFT_TO_RIGHT",
"sectionType": "CONTINUOUS"
}
}
},
{
"startIndex": 1,
"endIndex": 59,
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 5,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
},
{
"startIndex": 5,
"endIndex": 20,
"textRun": {
"content": "CONTENT",
"textStyle": {
"bold": true
}
}
},
{
"startIndex": 20,
"endIndex": 59,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
},
{
... // style details
},
"revisionId": "REVISION_ID",
"suggestionsViewMode": "SUGGESTIONS_INLINE",
"documentId": "DOCUMENT_ID"
}