Best practice per ottenere i risultati migliori

Esistono diversi principi da seguire quando si utilizza l'API Documenti Google. come le seguenti.

  • Modifica all'indietro per una maggiore efficienza
  • Pianifica la collaborazione
  • Garantisci la coerenza dello stato utilizzando il WriteControl campo
  • Tieni conto delle schede

Le sezioni seguenti spiegano questi principi.

Modifica all'indietro per una maggiore efficienza

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

Pianifica la collaborazione

Prevedi che lo stato del documento cambi. Tra una chiamata al metodo e l'altra, altri collaboratori potrebbero aggiornare il documento, come mostrato nel seguente diagramma:

Come può cambiare un documento tra le chiamate di metodi.

Questo può causare errori se gli indici non sono corretti. Se più utenti modificano un documento utilizzando l'interfaccia utente, Documenti Google si occupa di questo in modo trasparente. Tuttavia, in qualità di client API, la tua app deve gestire questa situazione. Anche se non prevedi la collaborazione sul documento, è importante programmare in modo difensivo e assicurarsi che lo stato del documento rimanga coerente. Per un modo per garantire la coerenza, consulta la WriteControl sezione.

Stabilisci la coerenza dello stato con WriteControl

Quando leggi e poi aggiorni un documento, puoi controllare il comportamento della gestione delle modifiche in conflitto utilizzando il WriteControl campo nel metodo documents.batchUpdate. WriteControl fornisce l'autorità su come vengono eseguite le richieste di scrittura.

Ecco come utilizzarlo:

  1. Recupera il documento utilizzando il documents.get metodo e salva il revisionId dalla risorsa documents restituita.
  2. Componi le richieste di aggiornamento.
  3. Includi un oggetto WriteControl facoltativo con una delle due opzioni:
    1. Il campo requiredRevisionId è impostato su revisionId del documento a cui viene applicata la richiesta di scrittura. Se il documento è stato modificato dopo la richiesta di lettura dell'API, la richiesta di scrittura non viene elaborata e restituisce un errore.
    2. Il campo targetRevisionId è impostato su revisionId del documento a cui viene applicata la richiesta di scrittura. Se il documento è stato modificato dopo la richiesta di lettura dell'API, le modifiche della richiesta di scrittura vengono applicate alle modifiche del collaboratore. Il risultato della richiesta di scrittura incorpora sia le modifiche della richiesta di scrittura sia le modifiche del collaboratore in una nuova revisione del documento. Il server di Documenti è responsabile dell'unione dei contenuti.

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

Tieni conto delle schede

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

Ecco cosa ricordare:

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