Richieste batch

Questo documento mostra come raggruppare le chiamate API in batch per ridurre il numero di connessioni che il client deve stabilire. Il batching può migliorare la capacità di efficienza riducendo i viaggi di andata e ritorno di rete e aumentando la velocità effettiva.

Panoramica

Ogni connessione effettuata dal client determina una determinata quantità di overhead. L'API Google Documenti supporta la creazione in batch per consentire al cliente di posizionare più oggetti di richiesta, ognuno dei quali specifica un singolo tipo di richiesta da eseguire, in una singola richiesta batch. Una richiesta batch può migliorare le prestazioni combinando più richieste secondarie in un'unica chiamata al server, recuperando una singola risposta.

Invitiamo gli utenti a raggruppare più richieste insieme. Ecco alcuni esempi esempi di situazioni in cui è possibile utilizzare la creazione in batch:

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

Limiti, autorizzazione e considerazioni sulle dipendenze

Di seguito sono riportati un elenco di altri elementi da considerare quando si utilizza l'aggiornamento batch:

  • Ogni richiesta batch, incluse tutte le richieste secondarie, viene conteggiata come un'unica API ai fini del limite di utilizzo.
  • Una richiesta batch viene autenticata una volta. Questa autenticazione unica si applica a tutti gli oggetti di aggiornamento batch nella richiesta.
  • Il server elabora le richieste secondarie nello stesso ordine in cui appaiono nel in una 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 applicarne uno stile.

Dettagli batch

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

Ogni richiesta viene convalidata prima di essere applicata. Tutte le richieste secondarie nel batch vengono applicati a livello 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 in batch per l'aggiunta di oggetti restituiscono risposte in modo che puoi accedere ai metadati dell'oggetto appena aggiunto, come l'ID o 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ù file, richieste secondarie nidificate con una proprietà obbligatoria: requests. La vengono create 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 batch

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

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

Esempio

Il seguente esempio di codice mostra l'utilizzo della creazione in batch con l'API Documenti.

Richiesta

Questa richiesta batch di esempio dimostra come:

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

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

  • Utilizzando textStyle, imposta lo stile del carattere in grassetto e il colore su blu per la parola "Hello".

  • Utilizzando il campo WriteControl, puoi controllare la modalità di esecuzione delle richieste di scrittura. Per maggiori informazioni consulta la sezione 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 l'ID tab e l'ID revisione, rispettivamente, del documento della richiesta di scrittura a cui viene applicata.

Risposta

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

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