Documento

Questa guida introduce concetti quali i metodi principali che compongono il l'API Documenti Google, come accedere a un documento e il flusso di lavoro documento.

Metodi dell'API

La risorsa documents fornisce che utilizzi per richiamare l'API Documenti. I seguenti metodi ti consentono creare, leggere e aggiornare documenti di Documenti:

  • Utilizza la documents.create per creare un documento.
  • Utilizza il metodo documents.get per recuperare i contenuti di un documento specificato.
  • Utilizza la documents.batchUpdate per eseguire atomicamente un insieme di aggiornamenti su un documento specificato.

I metodi documents.get e documents.batchUpdate richiedono un documentId parametro per specificare il documento di destinazione. Il metodo documents.create restituisce un'istanza del documento creato, da cui puoi leggere documentId. Per ulteriori informazioni sulle richieste dell'API Documenti e di risposta, consulta la sezione Richieste e risposte personalizzate.

ID documento

documentId è l'identificatore univoco del documento e può essere ricavato dall'URL di un documento. Si tratta di una particolare stringa contenente lettere, numeri e alcuni caratteri speciali. Gli ID documento sono stabili, anche se il nome del documento modifiche.

https://docs.google.com/document/d/DOCUMENT_ID/edit

La seguente espressione regolare può essere utilizzata per estrarre documentId da un URL di Documenti Google:

/document/d/([a-zA-Z0-9-_]+)

Se hai familiarità con l'API Google Drive, documentId corrisponde a id nella risorsa files.

Gestire documenti in Google Drive

I file di Documenti vengono archiviati su Google Drive, il nostro spazio di archiviazione basato su cloud completamente gestito di Google Cloud. Sebbene l'API Documenti abbia i propri metodi autonomi, spesso necessario utilizzare anche i metodi dell'API Google Drive per interagire con il Documenti Google. Ad esempio, per copiare i file di Documenti, utilizza il metodo files.copy dell'API Drive. Per ulteriori informazioni, consulta la sezione Copiare un modello esistente documento.

Per impostazione predefinita, quando utilizzi l'API Documenti, un nuovo documento viene salvato nel nella cartella principale dell'utente su Drive. Esistono opzioni per salvare un file in una cartella di Drive. Per ulteriori informazioni, vedi Utilizzare Cartelle di Google Drive.

Lavora con i file di Documenti

Per recuperare un documento da Il mio Drive di un utente, viene spesso necessarie per utilizzare per la prima volta files.list per recuperare il ID di un file. La chiamata del metodo senza parametri restituisce un elenco di tutte i file e le cartelle dell'utente, inclusi gli ID.

Il tipo MIME di un documento indica il tipo e il formato dei dati. Il formato del tipo MIME per Documenti è application/vnd.google-apps.document. Per un elenco di Tipi MIME, consulta la documentazione su Google Workspace e Google Drive supportati di classificazione.

Per cercare in base al tipo MIME solo i file di Documenti all'interno di My Drive, aggiungi il seguente filtro per la stringa di query:

q: mimeType = 'application/vnd.google-apps.document'

Per ulteriori informazioni sui filtri delle stringhe di query, vedi Cercare file e cartelle.

Quando conosci documentId, usa Metodo documents.get da recuperare un'istanza completa del documento specificato. Per ulteriori informazioni, vedi Richieste e risposte.

Per esportare i contenuti byte dei documenti di Google Workspace, utilizza files.export con il metodo documentId del file da esportare e il file MIME di esportazione corretto tipo. Per ulteriori informazioni, consulta la sezione Esportazione Documento di Google Workspace .

Confronta i metodi Get e List

Nella tabella seguente vengono descritte le differenze tra i file di Drive e Documenti, nonché i dati che vengono restituiti con ciascuno di essi:

Operatore Descrizione Utilizzo
drive.files.get Recupera i metadati di un file in base all'ID. Restituisce un'istanza della risorsa files. Ottieni i metadati per un file specifico.
drive.files.list Restituisce i file di un utente. Restituisce un elenco di file. Recupera un elenco di file utente quando non sai con certezza quale file devi modificare.
docs.documents.get Recupera la versione più recente del documento specificato, inclusi tutta la formattazione e il testo. Restituisce un'istanza della risorsa documents. Ottieni il documento per un ID documento specifico.

Flusso di lavoro per la creazione di documenti

Creare e compilare un nuovo documento è semplice, in quanto non esiste contenuti esistenti di cui preoccuparsi e nessun collaboratore può modificare lo stato del documento. Concettualmente, questo funziona come mostrato nella sequenza seguente diagramma:

Flusso di lavoro per la creazione per compilare un nuovo documento.
Figura 1. Flusso di lavoro per creare e compilare un nuovo documento.

Nella figura 1, un utente che interagisce con La risorsa documents ha quanto segue flusso di informazioni:

  1. Un'app chiama Metodo documents.create attivo un server web.
  2. Il server web invia una risposta HTTP che contiene un'istanza del documento creato come risorsa documents.
  3. Facoltativamente, l'app chiama documents.batchUpdate per eseguire atomicamente un insieme di richieste di modifica per compilare il documento con i dati.
  4. Il server web invia una risposta HTTP. Alcuni metodi di documents.batchUpdate fornire un corpo della risposta con informazioni sulle richieste applicate, mentre gli altri fanno emergere una risposta vuota.

Flusso di lavoro di aggiornamento dei documenti

Aggiornare un documento esistente è più complesso. Prima di rendere significativo l'esperienza per aggiornare un documento, devi conoscerne lo stato attuale: quali elementi i contenuti e l'ordine degli elementi del documento. Il seguente diagramma di sequenza mostra come funziona:

Flusso di lavoro per l'aggiornamento di un documento.
Figura 2. Flusso di lavoro per l'aggiornamento di un documento.

Nella Figura 2, un utente che interagisce con la risorsa documents ha il seguente flusso di informazioni:

  1. Un'app chiama Metodo documents.get su un sito web server, con documentId del file da trovare.
  2. Il server web invia una risposta HTTP che contiene un'istanza del specificato come risorsa documents. Il JSON restituito contiene i contenuti dei documenti, la formattazione e altre funzionalità.
  3. L'app analizza il codice JSON in modo che l'utente possa determinare i contenuti o il formato da usare aggiornamento.
  4. L'app chiama il metodo documents.batchUpdate per eseguire atomicamente un set di modifiche per aggiornare il documento.
  5. Il server web invia una risposta HTTP. Alcuni metodi documents.batchUpdate forniscono un corpo di risposta con informazioni sulle richieste applicate, mentre altri mostrano una risposta vuota.

Questo diagramma non considera i flussi di lavoro in cui gli aggiornamenti simultanei nello stesso documento sono creati collaboratori. Per ulteriori informazioni, vedi le sezione delle procedure "Pianificare per e la collaborazione.