Best practice per ottenere i risultati migliori

Esistono diversi principi da seguire quando utilizzi l'API Google Documenti. Queste includono:

  • Modifica a ritroso per migliorare l'efficienza
  • Piano per la collaborazione
  • Garantisci la coerenza dello stato utilizzando WriteControl campo
  • Prendi in considerazione le schede

Le sezioni seguenti spiegano questi principi.

Modifica a ritroso per migliorare l'efficienza

Nell'ambito di una singola chiamata documents.batchUpdate , ordina le richieste ordine decrescente della posizione dell'indice. In questo modo non è necessario calcolare modifiche all'indice dovute a inserimenti ed eliminazioni.

Piano per la collaborazione

Lo stato del documento dovrebbe cambiare. Tra una chiamata al metodo e un'altra, i collaboratori possono aggiornare il documento, come illustrato nel seguente diagramma:

Come un documento può cambiare tra una chiamata di metodo e l'altra.

Ciò può causare errori se gli indici sono errati. Quando più utenti modificano un documento utilizzando l'interfaccia utente, Documenti Google se ne occupa in modo trasparente. Tuttavia, Come client API, la tua app deve gestirlo. Anche se non prevedi collaborazione sul documento, è importante programmare in modo difensivo e che lo stato del documento rimanga coerente. Per garantire la coerenza, consulta la sezione WriteControl.

Stabilisci la coerenza dello stato conWriteControl

Quando leggi e poi aggiorni un documento, puoi controllare il comportamento delle le modifiche concorrenti vengono gestite WriteControl nel metodo documents.batchUpdate. WriteControl fornisce autorità le modalità di esecuzione delle richieste di scrittura.

Ecco come lo utilizzi:

  1. Scarica il documento utilizzando documents.get e salva il revisionId dalla risorsa documents restituita.
  2. Scrivi le richieste di aggiornamento.
  3. Includi un elemento WriteControl facoltativo con una delle due opzioni disponibili:
    1. Il campo requiredRevisionId è impostato sul valore revisionId del documento a cui viene applicata la richiesta di scrittura. Se il documento è stato modificato poiché la richiesta di lettura dell'API, la richiesta di scrittura non viene elaborata, restituisce un errore.
    2. Il campo targetRevisionId è impostato sul valore revisionId del documento a cui viene applicata la richiesta di scrittura. Se il documento è stato modificato dopo il API di lettura, le modifiche alla richiesta di scrittura vengono applicate le modifiche del collaboratore. Il risultato della richiesta di scrittura incorpora la richiesta di scrittura cambia e il collaboratore cambia in una nuova la revisione del documento. Il server di Documenti è responsabile per unire i contenuti.

Per un esempio di come costruire una richiesta batch utilizzando WriteControl, consulta questo esempio di richiesta in batch.

Prendi in considerazione le schede

Un singolo documento può contenere più schede, che richiedono una gestione specifica delle richieste API.

Ecco alcune informazioni da ricordare:

  1. Imposta il parametro includeTabsContent su true nel documents.get per recupera i contenuti da tutte le schede di un documento. Per impostazione predefinita, non tutte le schede vengono restituiti i contenuti.
  2. Specifica gli ID delle schede da applicare a ogni Request da nel documents.batchUpdate . Ogni Request include un modo per specificare le schede a cui applicare l'aggiornamento. Per impostazione predefinita, se non è specificata, Request nella maggior parte dei casi verrà applicata alla prima scheda del documento. Consulta le Request documentazione per le specifiche.