Usa le maschere di campo

Le maschere di campo consentono ai chiamanti API di elencare i campi che una richiesta deve restituire o aggiornare. L'utilizzo di un FieldMask consente all'API di evitare lavoro non necessario e migliora il rendimento. Una maschera di campo viene utilizzata sia per i metodi di lettura che di aggiornamento nell'API Google Docs.

Lettura con una maschera dei campi

I documenti possono essere di grandi dimensioni e spesso non hai bisogno di ogni parte della risorsa Document restituita da una richiesta di lettura. Puoi limitare i contenuti restituiti in una risposta dell'API Docs utilizzando il parametro URL fields. Per ottenere il massimo 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 sono separati da punti. I nomi dei campi possono essere specificati in camelCase o separated_by_underscores. Per comodità, più campi secondari dello stesso tipo possono essere elencati tra parentesi.

L'esempio di richiesta documents.get seguente utilizza una maschera di campo title,tabs(documentTab(body.content(paragraph))),revisionId per recuperare title del documento, Paragraph di un oggetto Body (da tutte le schede) e 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 del campo:

{
  "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 devi aggiornare solo determinati campi di un oggetto lasciando invariati gli altri campi. Le richieste di aggiornamento all'interno di un'operazione documents.batchUpdate utilizzano le maschere dei campi per comunicare all'API quali campi vengono modificati. La richiesta di aggiornamento ignora tutti i campi non specificati nella maschera del campo, 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 precedentemente presente nel campo.

La sintassi per le maschere dei campi di aggiornamento è la stessa delle maschere dei campi di lettura.

Una maschera di campo * viene trattata come un carattere jolly ed è una notazione abbreviata per specificare ogni campo di un messaggio. La sintassi con caratteri jolly può produrre risultati indesiderati se l'API viene aggiornata in futuro, poiché i campi di sola lettura e i campi appena aggiunti potrebbero causare errori. Per le applicazioni di produzione, elenca sempre i campi specifici da aggiornare nelle maschere dei campi ed evita di utilizzare caratteri jolly *.

Il seguente esempio utilizza UpdateTextStyleRequest per applicare lo stile in grassetto alle parole "API Google Docs" nel documento all'interno di 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
        },
      }
    }
  ],
}