Usa le maschere di campo

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 di aggiornamento nell'API Documenti Google.

Lettura con una maschera di campo

I documenti possono essere di grandi dimensioni e spesso non è necessaria ogni parte della risorsa Document restaurata da una richiesta di lettura. Puoi limitare i dati restituiti in una risposta dell'API Docs 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 è uguale alla 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.

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 di 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 è 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 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.

Una maschera di campo * viene trattata come una stringa jolly e rappresenta un'abbreviazione per specificare ogni campo di un messaggio. La sintassi dei caratteri jolly può produrre risultati indesiderati se l'API viene aggiornata in futuro, poiché i campi di sola lettura e quelli 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 i caratteri jolly *.

L'esempio seguente utilizza il carattere UpdateTextStyleRequest per applicare lo stile in grassetto alle parole "API Documenti Google" nel documento tra range 5 e 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
        },
      }
    }
  ],
}