Richieste batch

Questo documento mostra come raggruppare le chiamate API per ridurre il numero di connessioni che il client deve effettuare. Il batching può migliorare l'efficienza di un'applicazione diminuendo i viaggi di andata e ritorno della rete e aumentando la velocità effettiva.

Panoramica

Ogni connessione stabilita dal cliente comporta un determinato overhead. L'API Documenti Google supporta il raggruppamento per consentire al client di inserire più oggetti di richiesta, ciascuno che 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 e recuperando una singola risposta.

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

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

Considerazioni su limiti, autorizzazioni e dipendenze

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

  • Ogni richiesta in 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 collettivo nella richiesta.
  • Il server elabora le richieste secondarie nell'ordine in cui appaiono nella richiesta batch. Queste ultime 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 applicargli uno stile.

Dettagli del batch

Una richiesta in batch è composta da una chiamata al metodo batchUpdate con più richieste secondarie per, ad esempio, aggiungere e formattare un documento.

Ogni richiesta viene convalidata prima di essere applicata. Tutte le richieste secondarie nell'aggiornamento collettivo vengono applicate in modo atomico. In altre parole, 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 l'aggiunta di oggetti restituiscono risposte in modo da poter accedere ai metadati dell'oggetto appena aggiunto, ad esempio l'ID o il titolo.

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

Formato di una richiesta batch

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

Formato di una risposta collettiva

Il formato della risposta per una richiesta batch è simile al formato della richiesta. La risposta del server contiene una risposta completa del singolo oggetto risposta.

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 nell'indice dell'array è vuota.

Esempio

Il seguente esempio di codice mostra l'utilizzo del raggruppamento con l'API Docs.

Richiesta

Questa richiesta batch di esempio mostra come:

  • Inserisci il testo "Hello World" all'inizio di un documento esistente, con un location indice di 1, utilizzando InsertTextRequest.

  • Aggiorna la parola "Un saluto da Google" utilizzando UpdateTextStyleRequest. startIndex e endIndex definiscono il range del testo formattato all'interno del segmento.

  • Utilizzando textStyle, imposta lo stile del carattere su grassetto e il colore su blu solo per la parola "Un saluto da Google".

  • Utilizzando il campo WriteControl, puoi controllare la modalità di esecuzione delle richieste di scrittura. Per ulteriori informazioni, consulta Stabilire la coerenza dello stato con WriteControl.

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1,
               "tabId":TAB_ID
            },
            "text":"Hello World"
         }
      },
      {
         "updateTextStyle":{
            "range":{
               "startIndex":1,
               "endIndex":6
            },
            "textStyle":{
               "bold":true,
               "foregroundColor":{
                  "color":{
                     "rgbColor":{
                        "blue":1
                     }
                  }
               }
            },
            "fields":"bold,foreground_color"
         }
      }
   ],
   "writeControl": {
      "requiredRevisionId": "REQUIRED_REVISION_ID"
  }
}

Sostituisci TAB_ID e REQUIRED_REVISION_ID con rispettivamente l'ID scheda e l'ID revisione del documento a cui viene applicata la richiesta di scrittura.

Risposta

Questa risposta batch di esempio mostra informazioni su come è stata applicata ogni richiesta secondaria all'interno della richiesta batch. Né InsertTextRequest o UpdateTextStyleRequest contengono una risposta, pertanto i valori dell'indice della matrice in [0] e [1] sono costituiti da parentesi graffe vuote. La richiesta batch mostra l'oggetto WriteControl, che mostra come sono state eseguite le richieste.

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}