Le maschere di campo consentono ai chiamanti dell'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 per quelli di aggiornamento nell'API di Documenti Google.
Lettura con una maschera di campo
I documenti possono essere di grandi dimensioni e spesso non è necessario che ogni parte della risorsa Document venga restituita da una richiesta di lettura. Puoi limitare i dati restituiti in una risposta dell'API Docs utilizzando il parametro URL fields. Per ottenere le migliori prestazioni, elenca esplicitamente solo i campi necessari nella risposta.
Il formato del parametro fields è lo stesso della codifica JSON di un FieldMask. In breve, più campi diversi sono separati da virgole, mentre i campi secondari sono separati 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.
L'esempio di richiesta
documents.get seguente utilizza una maschera di campo di title,tabs(documentTab(body.content(paragraph))),revisionId
per recuperare il title del documento, il Paragraph
di un oggetto Body (da tutte le
schede) e il revisionId del documento all'interno di un documento:
GET https://docs.googleapis.com/v1/documents/documentId?fields=title,tabs(documentTab(body.content(paragraph))),revisionId
La risposta a questa chiamata al metodo è un oggetto Document contenente i componenti richiesti nella maschera dei campi:
{
"title": "TITLE",
"revisionId": "REVISION_ID",
"tabs": [
{
"documentTab": {
"body": {
"content": [
{},
{
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 59,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
}
}
}
]
}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 documents.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 che aveva il campo in precedenza.
La sintassi delle maschere dei campi di aggiornamento è la stessa delle maschere dei campi di lettura.
L'esempio seguente utilizza UpdateTextStyleRequest per definire in grassetto le parole "API Documenti Google" nel documento all'interno dei range 5-20:
POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{
"title": "TITLE",
"revisionId": "REVISION_ID",
"suggestionsViewMode": "SUGGESTIONS_INLINE",
"documentId": "DOCUMENT_ID",
"tabs": [
{
"documentTab": {
"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
},
}
}
],
}