Best practice per ottenere i risultati migliori

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 all'indice dovute a inserimenti ed eliminazioni.

Pianificare 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:

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 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 difensivo e garantire 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 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:

  1. Recupera il documento utilizzando il metodo documents.get 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 sul valore revisionId 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.
    2. Il campo targetRevisionId è impostato sul valore revisionId 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.

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:

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