Questa guida introduce i metodi principali di richiesta e risposta che compongono l'API Google Docs e spiega come aggiornare un documento in batch.
Puoi richiamare l'API Google Docs utilizzando una richiesta HTTP o un'invocazione di metodo in una libreria client specifica per la lingua. Questi sono ampiamente equivalenti.
L'API Google Docs restituisce una risposta HTTP, che in genere include il risultato dell'invocazione della richiesta. Quando utilizzi una libreria client per effettuare richieste, le risposte vengono restituite in modo specifico per la lingua.
Metodi di richiesta
L'API Docs supporta i seguenti metodi:
documents.create: Crea un documento Google vuoto.documents.get: Restituisce un'istanza completa del documento specificato. Puoi analizzare il JSON restituito per estrarre i contenuti, la formattazione e altre funzionalità del documento.documents.batchUpdate: Invia un elenco di richieste di modifica da applicare in modo atomico al documento e restituisci un elenco di risultati.
I metodi documents.get e documents.batchUpdate richiedono un documentId
come parametro per specificare il documento di destinazione. Il metodo documents.create restituisce un'istanza del documento creato, da cui puoi leggere documentId. Per maggiori informazioni su documentId, consulta la sezione ID documento.
Tieni presente che non puoi utilizzare il metodo documents.get per recuperare i documenti pubblicati. Una volta pubblicati, i documenti pubblici utilizzano un formato URL diverso. I tentativi
di utilizzare il nuovo documentId dell'URL con il metodo documents.get restituiscono una
risposta con codice di stato HTTP 404. Non esistono metodi per recuperare l'documentId originale dall'URL pubblicato. Per risolvere questo problema, puoi utilizzare l'API Drive per copiare il documento pubblicato in un documento condiviso e accedere a questo file. Per saperne di più, vedi
Rendere pubblici file di Documenti, Fogli, Presentazioni e
Moduli Google.
Aggiornamenti batch
Il metodo
documents.batchUpdate
accetta un elenco di
oggetti request,
ognuno dei quali specifica una singola richiesta da eseguire. Ad esempio, formatta un paragrafo
e poi aggiungi un'immagine in linea. Ogni richiesta viene convalidata prima di essere applicata e
le richieste vengono elaborate in base all'ordine in cui vengono visualizzate nella richiesta
batch.
Tutte le richieste nell'aggiornamento batch vengono applicate in modo atomico. ovvero, se una richiesta non è valida, l'intero aggiornamento non va a buon fine e nessuna delle modifiche (potenzialmente dipendenti) viene applicata.
Alcuni metodi documents.batchUpdate forniscono risposte con informazioni sulle richieste applicate. Questi metodi restituiscono un corpo
della risposta
che contiene un elenco di
oggetti response.
Le altre richieste non devono restituire informazioni e mostrano una risposta vuota. Gli
oggetti nell'elenco delle risposte occupano lo stesso ordine di indice della
richiesta corrispondente.
Un pattern comune per effettuare richieste batch è il seguente:
requests = []
requests.append(first request)
requests.append(second request)
...
body = ... & requests & ...
...batchUpdate(body)
Consulta le best practice per le richieste batch per i dettagli
completi su come raggruppare le chiamate API Docs e la
documentazione di riferimento documents.batchUpdate per i tipi di richiesta e risposta.
Operazioni di aggiornamento batch
Esistono vari tipi di richieste di aggiornamento collettivo. Ecco una suddivisione dei tipi di richieste, raggruppati in diverse categorie.
Argomenti correlati
- Struttura di un documento Google Docs
- Regole e comportamento di modifica strutturale
- Richieste batch