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 vuoto di Documenti Google.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 l'documentId. Per saperne di più su documentId, consulta ID documento.
Documenti pubblicati
Non puoi utilizzare il metodo documents.get per recuperare i documenti pubblicati. Una volta
pubblicati, i documenti pubblici utilizzano un formato URL diverso con un documentId pubblico
distinto. I tentativi di utilizzare documentId pubblico con il metodo documents.get
restituiscono un codice di stato HTTP 404.
Allo stesso modo, non puoi utilizzare il metodo
files.copy dell'API Drive per copiare un
documento pubblicato.
Per recuperare o copiare un documento pubblicato, devi utilizzare il documentId originale. Non esistono metodi per estrarre il documentId originale da un URL pubblicato.
Per ulteriori informazioni, vedi:
- Rendere pubblici file di Documenti, Fogli, Presentazioni e Moduli Google
- Copiare un documento esistente
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.
Altre richieste non devono restituire informazioni e mostrare 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 ha il seguente aspetto:
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 in batch le chiamate all'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