Esistono diversi principi da seguire quando utilizzi l'API Google Documenti. Questi includono:
- Modifica a ritroso per migliorare l'efficienza
- Piano per la collaborazione
- Assicurati che lo stato sia coerente utilizzando il campo
WriteControl
Le sezioni seguenti spiegano questi principi.
Modifica a ritroso per migliorare l'efficienza
All'interno di una singola chiamata al metodo documents.batchUpdate
, ordina le richieste in ordine decrescente della posizione dell'indice. In questo modo non è necessario calcolare le modifiche all'indice dovute a inserimenti ed eliminazioni.
Piano per la collaborazione
Lo stato del documento dovrebbe cambiare. Tra una chiamata di metodo e un'altra, altri collaboratori potrebbero aggiornare il documento, come mostrato nel diagramma seguente:
Ciò può causare errori se gli indici sono errati. Poiché più utenti modificano un
documento utilizzando l'interfaccia utente, Documenti Google se ne occupa in modo trasparente. Tuttavia,
in qualità di client API, la tua app deve gestire queste operazioni. Anche se non prevedi di collaborare al documento, è importante programmare in modo difensivo e garantire che lo stato del documento rimanga coerente. 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 l'autorità su come vengono eseguite le richieste di scrittura.
Ecco come lo utilizzi:
- Recupera il documento utilizzando il metodo
documents.get
e salvarevisionId
dalla risorsadocuments
restituita. - Scrivi le richieste di aggiornamento.
- Includi un oggetto
WriteControl
facoltativo con una delle due opzioni:- Il campo
requiredRevisionId
è impostato sul valorerevisionId
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. - Il campo
targetRevisionId
è impostato sulrevisionId
del documento a cui viene applicata la richiesta di scrittura. Se il documento è stato modificato dopo la richiesta di lettura dell'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 che quelle dei collaboratori in una nuova revisione del documento. Il server di Documenti è responsabile dell'unione dei contenuti.
- Il campo
Per un esempio di come costruire una richiesta batch utilizzando WriteControl
, vedi
questo esempio di richiesta batch.