Best practice per ottenere i risultati migliori

Esistono diversi principi che devi seguire quando utilizzi l'API Google Docs. Questi includono:

  • Modifica a ritroso per migliorare l'efficienza
  • Pianifica la collaborazione
  • Garantisci la coerenza dello stato utilizzando il campo WriteControl

Le sezioni seguenti spiegano questi principi.

Modifica a ritroso per migliorare l'efficienza

In una singola chiamata al metodo documents.batchUpdate, ordina le richieste in ordine decrescente della posizione dell'indice. Questo elimina la necessità di calcolare le variazioni dell'indice dovute a posizionamenti ed eliminazioni.

Pianifica la collaborazione

Lo stato del documento potrebbe cambiare. Tra una chiamata al metodo e un'altra, altri collaboratori potrebbero aggiornare il documento, come mostrato nel seguente diagramma:

In che modo un documento può cambiare da una chiamata di metodo all'altra.

Questo può causare errori se gli indici sono errati. Poiché più utenti modificano un documento utilizzando l'interfaccia utente, Documenti Google si occupa di questo aspetto in modo trasparente. Tuttavia, in qualità di client API, la tua app deve gestirla. Anche se non prevedi la collaborazione al documento, è importante programmare in modo difensivo e assicurarti che lo stato del documento rimanga coerente. Per una soluzione per garantire la coerenza, consulta la sezione WriteControl.

Stabilisci la coerenza dello stato con WriteControl

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

Ecco come utilizzarlo:

  1. Ottieni il documento utilizzando il metodo documents.get e salva revisionId dalla risorsa documents restituita.
  2. Scrivi le richieste di aggiornamento.
  3. Includi un oggetto WriteControl facoltativo con una delle due opzioni seguenti:
    1. Il campo requiredRevisionId è impostato sul valore revisionId del documento a cui viene applicata la richiesta di scrittura. Se il documento è stato modificato dopo la richiesta di lettura API, la richiesta di scrittura non viene elaborata e 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 la richiesta di lettura API, le modifiche alla richiesta di scrittura vengono applicate alle modifiche del collaboratore. Il risultato della richiesta di scrittura incorpora sia le modifiche alla 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, vedi questo esempio di richiesta batch.