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 una FieldMask consente all'API di evitare lavoro non necessario e migliora le prestazioni. Una maschera di campo viene utilizzata sia per i metodi di lettura che di aggiornamento nell'API Google Sheets.

Lettura con una maschera di campo

I fogli di lavoro possono essere di grandi dimensioni e spesso non è necessario che ogni parte della Spreadsheet risorsa venga restituita da una richiesta di lettura. Puoi limitare ciò che viene restituito in una risposta dell'API Sheets utilizzando il parametro URL fields. Per ottenere prestazioni ottimali, elenca esplicitamente solo i campi di cui hai bisogno nella risposta.

Il formato del parametro fields è lo stesso della codifica JSON di una 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à, è possibile elencare più sottocampi dello stesso tipo tra parentesi.

L'esempio di richiesta spreadsheets.get seguente utilizza una maschera di campo sheets.properties(sheetId,title,sheetType,gridProperties)per recuperare solo l' ID del foglio, il titolo, SheetType, e GridProperties di un oggetto SheetProperties in tutti i fogli di un foglio di lavoro:

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)

La risposta a questa chiamata al metodo è un Spreadsheet oggetto contenente i componenti richiesti nella maschera di campo. Tieni presente che sheetType=OBJECT non contiene gridProperties:

{
  "sheets": [
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "TITLE",
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 1000,
          "columnCount": 25
        }
      }
    },
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "TITLE",
        "sheetType": "OBJECT"
      }
    }
  ]
}

Aggiornamento con una maschera di campo

A volte devi aggiornare solo determinati campi in un oggetto, lasciando invariati gli altri campi. Le richieste di aggiornamento all'interno di un' spreadsheets.batchUpdate operazione 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 campo, mantenendo 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 precedente del campo.

La sintassi delle maschere di campo di aggiornamento è la stessa delle maschere di campo di lettura.

Una maschera di campo * viene trattata come un carattere jolly ed è una scorciatoia per specificare ogni campo in 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 di campo ed evita di utilizzare i caratteri jolly *.

L'esempio seguente utilizza il AddSheetRequest per aggiungere un nuovo foglio di tipo Grid, bloccare la prima riga e colorare di rosso la scheda del nuovo foglio:

POST https://sheets.googleapis.com/v1/spreadsheets/spreadsheetId:batchUpdate

{
  "spreadsheetId": "SPREADSHEET_ID",
  "replies": [
    {
      "addSheet": {
        "properties": {
          "sheetId": SHEET_ID,
          "title": "TITLE",
          "index": 6,
          "sheetType": "GRID",
          "gridProperties": {
            "rowCount": 1000,
            "columnCount": 26,
            "frozenRowCount": 1
          },
          "tabColor": {
            "red": 0.003921569
          },
          "tabColorStyle": {
            "rgbColor": {
              "red": 0.003921569
            }
          }
        }
      }
    }
  ]
}