Best practice per ottenere i risultati migliori

Esistono diversi principi da seguire quando utilizzi l'API Google Docs. tra cui:

  • Modificare all'indietro per una maggiore efficienza
  • Pianificare la collaborazione
  • Garantisci la coerenza dello stato utilizzando il campo WriteControl.
  • Prendi in considerazione le schede

Le sezioni seguenti spiegano questi principi.

Modificare all'indietro per una 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

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.

Ciò può causare errori se gli indici sono errati. Quando più utenti modificano un documento utilizzando l'interfaccia utente, Documenti Google gestisce questa operazione 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 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 conflitto utilizzando il campo WriteControl nel metodo documents.batchUpdate. WriteControl fornisce l'autorità su come vengono eseguite le richieste di scrittura.

Ecco come si usa:

  1. Ottieni il documento utilizzando il metodo documents.get e salva 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 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 sul 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 alla richiesta di scrittura sia le modifiche del collaboratore in una nuova revisione del documento. Il server Documenti è responsabile dell'unione dei contenuti.

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

Prendi in considerazione le schede

Un singolo documento può contenere più schede, che richiedono una gestione 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 delle schede.
  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 una scheda non è specificata, il Request verrà applicato nella maggior parte dei casi alla prima scheda del documento. Per informazioni specifiche, consulta la documentazione di Request.