Richieste batch

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

Panoramica

Ogni connessione effettuata dal client genera un determinato overhead. L'API Google Docs supporta la creazione in batch per consentire al client di inserire più oggetti di richiesta, ciascuno 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 un'unica chiamata al server, recuperando una singola risposta.

Invitiamo gli utenti a raggruppare sempre più richieste. Ecco alcuni esempi di situazioni in cui puoi utilizzare la funzionalità di 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, autorizzazione e dipendenze

Di seguito è riportato un elenco di altri elementi da considerare quando si utilizza l'aggiornamento in batch:

  • Ogni richiesta batch, incluse tutte le sottorichieste, viene conteggiata come un'unica 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 vengono visualizzate nella richiesta batch. Le ultime richieste secondarie 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 assegnare loro uno stile.

Dettagli batch

Una richiesta batch consiste in una chiamata al metodo batchUpdate con più sottorichieste per, ad esempio, aggiungere e poi formattare un documento.

Ogni richiesta viene convalidata prima di essere applicata. Tutte le sottorichieste nell'aggiornamento batch vengono applicate a livello atomico. Ciò significa che se una richiesta non è valida, l'intero aggiornamento non andrà 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, permettendoti di accedere ai metadati dell'oggetto appena aggiunto, come l'ID o il titolo.

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

Formato di una richiesta batch

Una richiesta è una singola richiesta JSON contenente più sottorichieste nidificate con una proprietà obbligatoria: requests. Le richieste vengono create in un array di richieste singole. Ogni richiesta utilizza JSON per rappresentare l'oggetto della richiesta e contenerne le proprietà.

Formato di una risposta batch

Il formato della risposta per una richiesta batch è simile al formato 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 e ogni risposta a una delle richieste occupa lo stesso ordine di indicizzazione della richiesta corrispondente. Alcune richieste non hanno risposte e la risposta in questo indice dell'array è vuota.

Esempio

Il seguente esempio di codice mostra l'utilizzo della creazione in batch 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 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 su grassetto e il colore su blu solo per la parola "Ciao".

  • Utilizzando il campo WriteControl, puoi controllare il modo in cui vengono eseguite le richieste di scrittura. Per ulteriori informazioni, consulta Stabilire la coerenza dello stato con WriteControl.

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1
            },
            "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 REQUIRED_REVISION_ID con 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 né UpdateTextStyleRequest contengono una risposta, quindi i valori di indice dell'array 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`
}