Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
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
Tenere conto delle 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 è più necessario calcolare le
modifiche all'indice dovute a inserimenti ed eliminazioni.
Pianificare la collaborazione
Prevedi che lo stato del documento cambi. 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 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:
Ottieni il documento utilizzando il
metodo
documents.get
e salva
revisionId
dalla risorsa documents restituita.
Componi le richieste di aggiornamento.
Includi un oggetto WriteControl facoltativo con una delle due opzioni:
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.
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.
Tenere conto delle schede
Un singolo documento può contenere più schede,
che richiedono una gestione specifica nelle richieste API.
Ecco cosa devi ricordare:
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.
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, Request verrà applicato nella maggior parte dei casi alla prima scheda del documento. Per informazioni specifiche, consulta la documentazione di
Request.
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Mancano le informazioni di cui ho bisogno","missingTheInformationINeed","thumb-down"],["Troppo complicato/troppi passaggi","tooComplicatedTooManySteps","thumb-down"],["Obsoleti","outOfDate","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Problema relativo a esempi/codice","samplesCodeIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 2025-08-29 UTC."],[],[],null,["# Best practices for best results\n\nThere are several principles you should follow when using the Google Docs API.\nThese include:\n\n- Edit backwards for efficiency\n- Plan for collaboration\n- Ensure state consistency using the [`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol) field\n- Take tabs into account\n\nThe following sections explain these principles.\n\nEdit backwards for efficiency\n-----------------------------\n\nWithin a single call to the\n[`documents.batchUpdate`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate)\nmethod, order your requests in\n*descending order* of index location. This eliminates the need to compute the\nindex changes due to insertions and deletions.\n\nPlan for collaboration\n----------------------\n\nExpect the document state to change. Between one method call and another, other\ncollaborators might update the document, as shown in the following diagram:\n\nThis can lead to errors if your indexes are wrong. With multiple users editing a\ndocument using the UI, Google Docs takes care of this transparently. However,\nas an API client your app must manage this. Even if you don't anticipate\ncollaboration on the document, it's important to program defensively and make\nsure the document state remains consistent. For one way to ensure consistency,\nreview the [`WriteControl`](#establish-state-consistency) section.\n\nEstablish state consistency with WriteControl\n---------------------------------------------\n\nWhen you read and then update a document, you can control the behavior of how\ncompeting changes are handled using the\n[`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol)\nfield in the `documents.batchUpdate` method. `WriteControl` provides authority\nover how write requests are executed.\n\nHere's how you use it:\n\n1. Get the document using the [`documents.get`](/workspace/docs/api/reference/rest/v1/documents/get) method and save the [`revisionId`](/workspace/docs/api/reference/rest/v1/documents#Document.FIELDS.revision_id) from the returned `documents` resource.\n2. Compose your update requests.\n3. Include an optional [`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol) object with one of two options:\n 1. The `requiredRevisionId` field is set to the `revisionId` of the document the write request is applied to. If the document was modified since the API read request, the write request isn't processed and it returns an error.\n 2. The `targetRevisionId` field is set to the `revisionId` of the document the write request is applied to. If the document was modified since the API read request, the write request changes are applied against the collaborator changes. The result of the write request incorporates both the write request changes and the collaborator changes into a new revision of the document. The Docs server is responsible for merging the content.\n\nFor an example of how to construct a batch request using `WriteControl`, see\nthis [batch request example](/workspace/docs/api/how-tos/batch#example).\n\nTake tabs into account\n----------------------\n\nA single document can contain multiple [tabs](/workspace/docs/api/how-tos/tabs),\nwhich require specific handling in your API requests.\n\nHere's what to remember:\n\n1. Set the `includeTabsContent` parameter to `true` in the [`documents.get`](/workspace/docs/api/reference/rest/v1/documents/get) method to retrieve the content from all tabs in a document. By default, not all tab contents are returned.\n2. Specify the ID(s) of the tab(s) to apply each [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) to in the [`documents.batchUpdate`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate) method. Each [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) includes a way to specify the tabs to apply the update to. By default, if a tab is not specified, the [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) will in most cases be applied to the first tab in the document. Refer to the [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request)s documentation for specifics.\n\nRelated topics\n--------------\n\n- [Batch requests](/workspace/docs/api/how-tos/batch)\n- [Requests and responses](/workspace/docs/api/concepts/request-response)\n- [Work with tabs](/workspace/docs/api/how-tos/tabs)"]]
