Documento

Questa guida introduce concetti quali 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 puoi utilizzare per richiamare l'API Docs. I seguenti metodi consentono di creare, leggere e aggiornare i documenti di Documenti:

  • Utilizza il metodo documents.create per creare un documento.
  • Utilizza il metodo documents.get per recuperare i contenuti di un documento specificato.
  • Utilizza il metodo documents.batchUpdate per eseguire a livello atomico una serie 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, dalla quale puoi leggere il documentId. Per ulteriori informazioni sulle richieste e sui metodi di risposta dell'API Documenti, consulta Richieste e risposte.

ID documento

documentId è l'identificatore univoco del documento e può essere ricavato 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 conosci l'API Google Drive, documentId corrisponde a id nella risorsa files.

Gestire documenti in Google Drive

I file di Documenti sono archiviati su Google Drive, il nostro servizio di archiviazione basato su cloud. Sebbene l'API Docs abbia i propri metodi autonomi, spesso è necessario utilizzare anche 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 dell'API Drive files.copy. Per ulteriori informazioni, vedi Copiare un documento esistente.

Per impostazione predefinita, quando utilizzi l'API Docs, un nuovo documento viene salvato nella cartella principale dell'utente su Drive. Ci sono opzioni per salvare un file in una cartella di Drive. Per ulteriori informazioni, vedi Lavorare con le cartelle di Google Drive.

Lavorare con i file di Documenti

Per recuperare un documento dalla cartella 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 del metodo senza parametri restituisce un elenco di tutti i file e di tutte le cartelle, inclusi gli ID, dell'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, vedi Tipi MIME supportati per Google Workspace e Google Drive.

Per cercare solo i file di Documenti in Il mio Drive in base al tipo MIME, 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, consulta Ricerca di file e cartelle.

Quando conosci documentId, usa il metodo documents.get per recuperare un'istanza completa del documento specificato. Per maggiori informazioni, consulta Richieste e risposte.

Per esportare i contenuti di 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 maggiori informazioni, vedi Esportare i contenuti dei documenti di Google Workspace.

Confronta i metodi Get e List

La seguente tabella descrive le differenze tra i metodi di Drive e Documenti, nonché i dati restituiti con ciascuno:

Operatore Descrizione Utilizzo
drive.files.get Recupera i metadati di un file per ID. Restituisce un'istanza della risorsa files. Recupera i metadati per un file specifico.
drive.files.list Recupera i file di un utente. Restituisce un elenco di file. Ricevi un elenco dei file utente quando hai dubbi sul file da modificare.
docs.documents.get Recupera l'ultima versione del documento specificato, inclusi tutti i tipi di formattazione e di testo. Restituisce un'istanza della risorsa documents. Recupera il documento per uno specifico ID documento.

Flusso di lavoro per la creazione di documenti

Creare e compilare un nuovo documento è semplice, poiché non ci sono contenuti di cui preoccuparsi e non ci sono collaboratori in grado di modificarne lo stato. A livello concettuale, questo funzionamento è illustrato nel seguente schema di sequenza:

Flusso di lavoro per la creazione e il completamento di un nuovo documento.
Figura 1. Flusso di lavoro per creare e completare un nuovo documento.

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

  1. Un'app chiama il metodo documents.create su un server web.
  2. Il server web invia una risposta HTTP contenente un'istanza del documento creato come risorsa documents.
  3. Facoltativamente, l'app chiama il metodo documents.batchUpdate per eseguire a livello atomico un set 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

Aggiornare un documento esistente è più complesso. Prima di poter effettuare chiamate significative per aggiornare un documento, devi conoscerne lo stato attuale: gli elementi che lo compongono, i contenuti al loro interno e l'ordine degli elementi all'interno 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 il metodo documents.get su un server web, utilizzando il valore documentId del file da trovare.
  2. Il server web invia una risposta HTTP contenente un'istanza del documento specificato come risorsa documents. Il JSON restituito contiene i contenuti, la formattazione e altre caratteristiche del documento.
  3. L'app analizza il codice JSON in modo che l'utente possa determinare i contenuti o il formato da aggiornare.
  4. L'app chiama il metodo documents.batchUpdate per eseguire a livello atomico una serie 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 gli aggiornamenti simultanei di altri collaboratori vengono eseguiti nello stesso documento. Per ulteriori informazioni, consulta la sezione delle best practice Pianificare la collaborazione.