Quando utilizzi l'API Documenti Google, devi seguire diversi principi. Queste includono:
- Modifica da destra verso sinistra per maggiore efficienza
- Pianificare la collaborazione
- Garantire la coerenza dello stato utilizzando il
campo
WriteControl
- Tenere conto delle schede
Questi principi sono spiegati nelle sezioni che seguono.
Modifica da destra verso sinistra per maggiore 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 dell'indice dovute a inserzioni ed eliminazioni.
Pianificare la collaborazione
Lo stato del documento dovrebbe cambiare. Tra una chiamata di metodo e l'altra, altri collaboratori potrebbero aggiornare il documento, come mostrato nel seguente diagramma:
Ciò può causare errori se gli indici sono errati. Quando più utenti modificano un
documento utilizzando l'interfaccia utente, Documenti Google si occupa di tutto in modo trasparente. Tuttavia, come client API, è tua responsabilità gestire questo aspetto. Anche se non prevedi di collaborare al documento, è importante programmare in modo sicuro e assicurarti che lo stato del documento rimanga coerente. Per un modo per garantire la coerenza, consulta la sezione WriteControl
.
Stabilire la coerenza dello stato con WriteControl
Quando leggi e poi aggiorni un documento, puoi controllare il comportamento di 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 utilizzarlo:
- Recupera il documento utilizzando il metodo
documents.get
e salvarevisionId
dalla risorsadocuments
restituita. - Componi le richieste di aggiornamento.
- Includi un oggetto
WriteControl
facoltativo con una delle due opzioni:- Il campo
requiredRevisionId
è impostato surevisionId
del documento a cui viene applicata la richiesta di scrittura. Se il documento è stato modificato dall'ultima richiesta di lettura dell'API, la richiesta di scrittura non viene elaborata e viene restituito un errore. - Il campo
targetRevisionId
è impostato sul valorerevisionId
del documento a cui viene applicata la richiesta di scrittura. Se il documento è stato modificato dalla 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 apportate alla richiesta di scrittura sia le modifiche apportate dal collaboratore in una nuova revisione del documento. Il server di Documenti è responsabile dell'unione dei contenuti.
- Il campo
Per un esempio di come creare una richiesta batch utilizzando WriteControl
, consulta questo esempio di richiesta batch.
Tenere conto delle schede
Un singolo documento può contenere più schede, che richiedono un'elaborazione specifica nelle richieste API.
Ecco cosa devi ricordare:
- Imposta il parametro
includeTabsContent
sutrue
nel metododocuments.get
per recuperare i contenuti da tutte le schede di un documento. Per impostazione predefinita, non vengono restituiti tutti i contenuti della scheda. - Specifica gli ID delle schede a cui applicare ogni
Request
nel metododocuments.batchUpdate
. OgniRequest
include un modo per specificare le schede a cui applicare l'aggiornamento. Per impostazione predefinita, se non viene specificata una scheda,Request
verrà applicata nella maggior parte dei casi alla prima scheda del documento. Per informazioni specifiche, consulta la documentazione diRequest
.