Questa guida introduce i metodi di richiesta e risposta principali che compongono l'API Documenti Google e come aggiornare un documento in batch.
Puoi richiamare l'API Documenti Google utilizzando una richiesta HTTP o richiamando un metodo in una libreria client specifica per il linguaggio. Questi due approcci sono sostanzialmente equivalenti.
L'API Documenti Google restituisce una risposta HTTP, che in genere include il risultato della chiamata della richiesta. Quando utilizzi una libreria client per effettuare richieste, le risposte vengono restituite in modo specifico per il linguaggio.
Metodi di richiesta
L'API Documenti supporta i seguenti metodi:
documents.create: crea un documento di Documenti Google vuoto.documents.get: restituisce un'istanza completa del documento specificato. Puoi analizzare il JSON restituito per estrarre il contenuto, la formattazione e altre funzionalità del documento.documents.batchUpdate: invia un elenco di richieste di modifica da applicare in modo atomico al documento e restituisce 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 il documentId. Per ulteriori informazioni su documentId, vedi Documento
ID.
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 il documentId pubblico con il metodo documents.get restituiscono una risposta con codice di stato HTTP 404.
Allo stesso modo, non puoi utilizzare il metodo dell'API Drive
files.copy 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
documents.batchUpdate
metodo 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 incorporata. Ogni richiesta viene convalidata prima di essere applicata e le richieste vengono elaborate in base all'ordine in cui appaiono nella richiesta batch.
Tutte le richieste nell'aggiornamento batch vengono applicate in modo atomico. Ciò significa che, se una richiesta non è valida, l'intero aggiornamento non va a buon fine e non vengono applicate le modifiche (potenzialmente dipendenti).
Alcuni metodi documents.batchUpdate forniscono risposte con informazioni sulle richieste applicate. Questi metodi restituiscono un corpo
della risposta
che contiene un elenco di
response oggetti.
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)
Per informazioni dettagliate su come raggruppare in batch le chiamate all'API Documenti e sulla
documents.batchUpdate
documentazione di riferimento per i tipi di richiesta e risposta, consulta le best practice per le richieste batch.
Operazioni di aggiornamento batch
Esistono vari tipi di richieste di aggiornamento batch. Di seguito è riportata una suddivisione dei tipi di richiesta, raggruppati in diverse categorie.
Argomenti correlati
- Struttura di un documento di Documenti Google
- Regole e comportamento di modifica strutturale
- Richieste batch