L'API Documenti Google ti consente di creare e modificare documenti.
Le app possono integrarsi con l'API Documenti per creare documenti eleganti utilizzando sia i dati forniti dall'utente sia quelli forniti dal sistema. L'API consente di:
- Automatizzare i processi
- Crea documentazione in blocco
- Generare fatture o contratti
Panoramica dell'API
La risorsa documenti fornisce metodi che puoi utilizzare per richiamare l'API Documenti.
Metodi API
I seguenti metodi consentono di creare, leggere e aggiornare documenti Google:
- Utilizza documents.create per creare un documento.
- Utilizza documents.get per recuperare i contenuti di un documento specificato.
- Utilizza documents.batchUpdate per eseguire atomicamente una serie di aggiornamenti su un documento specificato.
I metodi get e batchUpdate richiedono un elemento documentId (vedi di seguito) come parametro per specificare il documento di destinazione. Il metodo create restituisce un'istanza del documento creato, da cui puoi leggere l'ID.
Aggiornamenti collettivi
Il metodo batchUpdate prende un elenco di oggetti richiesta ed esegue gli aggiornamenti secondo lo stesso ordine in cui appaiono nella richiesta batch. Gli aggiornamenti nell'aggiornamento batch vengono applicati in modo atomico. In altre parole, se una richiesta non è valida, l'intero aggiornamento non andrà a buon fine e non verrà applicata alcuna modifica (potenzialmente dipendente).
Il metodo batchUpdate restituisce un elenco di oggetti di risposta. Gli oggetti in questo elenco occupano lo stesso ordine di indicizzazione della richiesta corrispondente.
Consulta le best practice per le richieste in batch per informazioni su come raggruppare insieme le chiamate API e la documentazione di riferimento per batchUpdate per i tipi di richiesta e risposta.
ID documento
Gli ID documento fanno riferimento a un documento e possono essere ricavati dall'URL:
https://docs.google.com/document/d/documentId/edit
documentId è una stringa univoca contenente lettere, numeri e alcuni caratteri speciali. La seguente espressione regolare può essere utilizzata per estrarre l'ID documento da un URL di Documenti Google:
/document/d/([a-zA-Z0-9-_]+)
Se hai dimestichezza con l'API Google Drive, documentId corrisponde all'ID della risorsa File.
Posizione all'interno di un documento: indici
Quando apporti aggiornamenti ai contenuti di un documento, ogni aggiornamento avviene in una posizione o in un intervallo all'interno del documento. Queste località e intervalli vengono specificati utilizzando indici, che rappresentano un offset all'interno di un segmento documento. Per scoprire di più sugli indici e su come utilizzarli, consulta la guida tecnica del documento sulla struttura di un documento Google.
Flusso di lavoro per l'aggiornamento dei documenti
Creare e completare un nuovo documento è semplice, poiché non esistono contenuti di cui preoccuparsi e non ci sono collaboratori che possano modificarne lo stato. Concettualmente, funziona come mostrato nel seguente diagramma di sequenza:
L'aggiornamento di un documento esistente è più complesso. Prima di poter effettuare chiamate significative per aggiornare un documento, devi conoscere lo stato attuale del documento: quali elementi costituiscono, quali contenuti sono presenti e dove si trovano tutti questi elementi all'interno del documento. Il seguente diagramma di sequenza mostra come funziona:
Questo diagramma non considera i flussi di lavoro in cui nello stesso documento vengono effettuati aggiornamenti simultanei di altri collaboratori. Consulta Piano di collaborazione per una discussione su questo argomento.