Documento

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

Metodi dell'API

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

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

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 sui metodi di richiesta e risposta dell'API Documenti, consulta Richieste e risposte.

ID documento

documentId è l'identificatore univoco del documento e può essere derivato dall'URL di un documento. È una stringa particolare che contiene lettere, numeri e alcuni caratteri speciali. Gli ID documento sono stabili, anche se il nome del documento cambia.

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, il documentId corrisponde a id nella risorsa files.

Gestire documenti in Google Drive

I file di Documenti vengono archiviati in Google Drive, il nostro servizio di archiviazione basato sul cloud. Sebbene l'API Documenti abbia i propri metodi autonomi, spesso è necessario utilizzare anche i metodi dell'API Google Drive per interagire con i file di Documenti di un utente. Ad esempio, per copiare i file di Documenti, utilizza il metodo files.copy dell'API Drive. Per ulteriori informazioni, consulta Copiare un documento esistente.

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

Utilizzare i file di Documenti

Per recuperare un documento da Il mio Drive di un utente, spesso è necessario utilizzare prima il metodo files.list di Drive per recuperare l'ID di un file. La chiamata al metodo senza parametri restituisce un elenco di tutti i file e le cartelle, inclusi gli ID, per l'utente.

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 dei tipi MIME, consulta Tipi MIME supportati per Google Workspace e Google Drive tipi.

Per eseguire la ricerca per tipo MIME solo dei file di Documenti in Il mio Drive, aggiungi il seguente filtro della stringa di query:

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

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

Una volta che conosci documentId, utilizza il documents.get metodo per recuperare un'istanza completa del documento specificato. Per ulteriori informazioni, consulta Richieste e risposte.

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

Confrontare i metodi Get e List

La seguente tabella descrive le differenze tra i metodi di Drive e Documenti e i dati 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 files risorsa. Recupera i metadati di un file specifico.
drive.files.list Recupera i file di un utente. Restituisce un elenco di file. Recupera un elenco di file utente quando non sai quale file devi modificare.
docs.documents.get Recupera l'ultima versione del documento specificato, inclusi tutti i formattazione e il testo. Restituisce un'istanza della documents risorsa. Recupera il documento per un ID documento specifico.

Flusso di lavoro di creazione dei documenti

La creazione e il completamento di un nuovo documento sono semplici, poiché non ci sono contenuti esistenti di cui preoccuparsi e non ci sono collaboratori che possono modificare lo stato del documento. Concettualmente, funziona come mostrato nel seguente diagramma di sequenza:

Workflow per creare e compilare un nuovo documento.
Figura 1. Flusso di lavoro per creare e completare un nuovo documento.

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

  1. Un'app chiama il documents.create metodo su 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 il documents.batchUpdate metodo per eseguire in modo atomico un insieme di richieste di modifica per completare il documento con i dati.
  4. Il server web invia una risposta HTTP. Alcuni metodi documents.batchUpdate forniscono un corpo della risposta con informazioni sulle richieste applicate, mentre altri mostrano una risposta vuota.

Flusso di lavoro di aggiornamento dei documenti

L'aggiornamento di un documento esistente è più complesso. Prima di poter effettuare chiamate significative per aggiornare un documento, devi conoscerne lo stato attuale: quali elementi lo compongono, quali contenuti sono presenti in questi elementi e l'ordine degli elementi all'interno del documento. Il seguente diagramma di sequenza mostra come funziona:

Workflow per aggiornare un documento.
Figura 2. Flusso di lavoro per aggiornare un documento.

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

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

Questo diagramma non considera i flussi di lavoro in cui vengono apportati aggiornamenti simultanei da altri collaboratori nello stesso documento. Per ulteriori informazioni, consulta la sezione relativa alle best practice Pianificare la collaborazione.