Richieste batch

Questo documento mostra come effettuare chiamate API in batch per ridurre il numero di connessioni che il tuo client deve effettuare. Il batch può migliorare l'efficienza di un'applicazione riducendo i round trip di rete e aumentando la velocità effettiva.

Panoramica

Ogni connessione stabilita dal client comporta un determinato overhead. L'API Google Sheets supporta il raggruppamento in batch per consentire al client di inserire più oggetti richiesta, ognuno dei quali specifica un singolo tipo di richiesta da eseguire, in un'unica richiesta batch. Una richiesta batch può migliorare le prestazioni combinando più richieste secondarie in una singola chiamata al server, recuperando una singola risposta.

Invitiamo gli utenti a raggruppare sempre più richieste. Ecco alcuni esempi di situazioni in cui puoi utilizzare il raggruppamento in batch:

  • Hai appena iniziato a utilizzare l'API e hai molti dati da caricare.
  • Devi aggiornare i metadati o le proprietà, ad esempio la formattazione, di più oggetti.
  • Devi eliminare molti oggetti.

Considerazioni su limiti, autorizzazione e dipendenze

Ecco un elenco di altri elementi da considerare quando utilizzi l'aggiornamento batch:

  • Ogni richiesta batch, incluse tutte le richieste secondarie, viene conteggiata come una richiesta API ai fini del limite di utilizzo.
  • Una richiesta batch viene autenticata una sola volta. Questa singola autenticazione si applica a tutti gli oggetti di aggiornamento batch nella richiesta.
  • Il server elabora le richieste secondarie nello stesso ordine in cui appaiono nella richiesta batch. Le richieste secondarie successive possono dipendere dalle azioni intraprese durante le richieste secondarie precedenti. Ad esempio, nella stessa richiesta batch, gli utenti possono inserire testo in un documento esistente e poi formattarlo.

Dettagli batch

Una richiesta batch è costituita da una chiamata al metodo batchUpdate con più richieste secondarie, ad esempio per aggiungere e poi formattare un foglio di lavoro.

Ogni richiesta viene convalidata prima di essere applicata. Tutte le richieste secondarie nell'aggiornamento batch vengono applicate in modo atomico. ovvero, se una richiesta non è valida, l'intero aggiornamento non va a buon fine e nessuna delle modifiche (potenzialmente dipendenti) viene applicata.

Alcune richieste forniscono risposte con informazioni sulle richieste applicate. Ad esempio, tutte le richieste di aggiornamento batch per aggiungere oggetti restituiscono risposte in modo da poter accedere ai metadati dell'oggetto appena aggiunto, come l'ID o il titolo.

Con questo approccio, puoi creare un intero documento Google utilizzando una richiesta di aggiornamento batch API con più richieste secondarie.

Formato di una richiesta batch

Una richiesta è una singola richiesta JSON contenente più sottorequest nidificate con una proprietà obbligatoria: requests. Le richieste sono strutturate in un array di singole richieste. Ogni richiesta utilizza JSON per rappresentare l'oggetto richiesta e per contenere le relative proprietà.

Formato di una risposta batch

Il formato della risposta a una richiesta batch è simile a quello della richiesta. La risposta del server contiene una risposta completa dell'oggetto di risposta singolo.

La proprietà dell'oggetto JSON principale è denominata replies. Le risposte vengono restituite in un array, con ogni risposta a una delle richieste che occupa lo stesso ordine di indice della richiesta corrispondente. Alcune richieste non hanno risposte e la risposta in quell'indice dell'array è vuota.

Esempio

L'esempio seguente mostra l'utilizzo del raggruppamento in batch con l'API Sheets.

Richiesta

Questa richiesta batch di esempio mostra come:

Aggiungendo l'ID foglio nella richiesta, gli utenti possono utilizzarlo per altre richieste secondarie nella stessa chiamata API. Ciò migliora le prestazioni evitando un ciclo di scrittura-lettura-scrittura.

Per un elenco dei tipi di richieste di aggiornamento batch, raggruppati in diverse categorie, consulta la tabella nella sezione Operazioni di aggiornamento batch.

{
   "requests":[
      {
         "addSheet":{
            "properties":{
               "sheetId":123456
            }
         }
      },
      {
         "updateCells":{
            "start":{
               "sheetId":123456
            },
            "rows":[
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"hello"
                        }
                     }
                  ]
               },
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"world"
                        }
                     }
                  ]
               }
            ],
            "fields":"userEnteredValue"
         }
      },
      {
         "addNamedRange":{
            "namedRange":{
               "name":"newRange",
               "range":{
                  "sheetId":123456,
                  "endRowIndex":2
               }
            }
         }
      }
   ]
}

Risposta

Questa risposta batch di esempio mostra informazioni su come è stata applicata ogni richiesta secondaria all'interno della richiesta batch. Tieni presente che UpdateCellsRequest non contiene una risposta, quindi il valore dell'indice dell'array in [1] è costituito da parentesi graffe vuote.

"replies":[
   {
      "addSheet":{
         "properties":{
            "sheetId":123456,
            "title":"Sheet3",
            "index":2,
            "sheetType":"GRID",
            "gridProperties":{
               "rowCount":1000,
               "columnCount":26
            }
         }
      }
   },
   {
      
   },
   {
      "addNamedRange":{
         "namedRange":{
            "namedRangeId":"2104325079",
            "name":"newRange",
            "range":{
               "sheetId":123456,
               "startRowIndex":0,
               "endRowIndex":2,
               "startColumnIndex":0,
               "endColumnIndex":26
            }
         }
      }
   }
]