L'API Google Drive supporta diversi tipi di azioni di download ed esportazione, come elencato nella tabella seguente:
| Azioni di download |
|
||||
| Azioni di esportazione |
|
Nell'API Drive, un file blob si riferisce a qualsiasi file binario non elaborato archiviato su
Google Drive (come immagini, video e PDF) anziché a un
documento Google Workspace. Non si riferisce all'oggetto
Blob di JavaScript. Per
descrizioni dettagliate dei tipi di file menzionati qui, inclusi i file blob e
Google Workspace, consulta Tipi
di file.
Prima di scaricare o esportare i contenuti dei file, verifica che gli utenti possano scaricare il file utilizzando il campo
capabilities.canDownload
nella risorsa files.
Il resto di questo documento fornisce istruzioni dettagliate per eseguire questi tipi di azioni di download ed esportazione.
Scaricare i contenuti del file blob
Per scaricare un file blob archiviato su Drive, utilizza il metodo files.get con l'ID del file da scaricare e il
alt parametro
system.
Il parametro alt=media indica al server che è stato richiesto il download dei contenuti come formato di risposta alternativo.
Il parametro di sistema alt è disponibile in tutte le API REST di Google. Se utilizzi
una libreria client dell'API Drive, non devi impostare esplicitamente questo
parametro perché il metodo della libreria client aggiunge il parametro alt=media alla
richiesta HTTP sottostante.
I seguenti esempi di codice mostrano come utilizzare il metodo files.get per scaricare un file:
Apps Script
/**
* Downloads a file from Drive.
* @param {string} fileId The ID of the file to download.
* @return {Blob} The file content as a Blob.
*/
function downloadFile(fileId) {
var url = 'https://www.googleapis.com/drive/v3/files/' + fileId + '?alt=media';
var response = UrlFetchApp.fetch(url, {
headers: {
'Authorization': 'Bearer ' + ScriptApp.getOAuthToken()
}
});
return response.getBlob();
}
Java
Python
Node.js
PHP
.NET
curl
curl -L "https://www.googleapis.com/drive/v3/files/FILE_ID?alt=media" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--output "FILE_NAME"
Sostituisci quanto segue:
- FILE_ID: l'ID del file da scaricare.
- ACCESS_TOKEN: il token di accesso che concede l'accesso all'API.
- FILE_NAME: il nome del file di output.
I download di file avviati dalla tua app devono essere autorizzati con un ambito che consenta
l'accesso in lettura ai contenuti del file. Ad esempio, un'app che utilizza l'ambito
drive.readonly.metadata non è autorizzata a scaricare i contenuti del file.
Gli esempi di codice della libreria client utilizzano l'ambito del file drive con limitazioni che consente agli utenti di visualizzare e gestire tutti i tuoi file di Drive. Per saperne di più
sugli ambiti di Drive, consulta Scegliere gli ambiti dell'API Google Drive.
Gli utenti con autorizzazioni owner (per i file di Il mio Drive) o
organizer (per i file del Drive condiviso) possono limitare il download
tramite l'oggetto
DownloadRestrictionsMetadata. Per saperne di più, vedi Impedire agli utenti di scaricare, stampare o
copiare un file.
I file identificati come abusivi
(ad esempio software dannosi) possono essere scaricati solo dal proprietario.
Inoltre, il parametro di query acknowledgeAbuse deve essere impostato su true per
indicare che l'utente ha riconosciuto il rischio di scaricare software potenzialmente
indesiderato o altri file illeciti. La tua applicazione deve avvisare
l'utente in modo interattivo prima di utilizzare questo parametro di query.
Accedere ai dati dei file in memoria
Se la tua applicazione deve accedere ai dati del file direttamente in memoria (ad esempio, come buffer di byte) anziché salvarli su un disco locale, puoi modificare la richiesta della libreria client o elaborare lo stream restituito:
Node.js: per impostazione predefinita, la libreria client Node.js restituisce i contenuti del file come flusso
Readable. Per salvare il file sul disco locale:const fs = require('fs'); const dest = fs.createWriteStream('/path/to/dest/file.ext'); const response = await service.files.get( { fileId, alt: 'media' }, { responseType: 'stream' } ); response.data .on('end', () => { console.log('Download complete.'); }) .on('error', (err) => { console.error('Error downloading file.', err); }) .pipe(dest);In alternativa, per restituire i dati direttamente in memoria come
ArrayBufferanziché come stream, imposta il parametroresponseTypenelle opzioni della richiesta:const file = await service.files.get({ fileId, alt: 'media', }, { responseType: 'arraybuffer' }); // Convert the ArrayBuffer to a Node.js Buffer object. const buffer = Buffer.from(file.data);Python: l'esempio di codice Python per scaricare un file blob scrive già i blocchi di download in un oggetto
io.BytesIO()in memoria. Per accedere ai byte non elaborati, chiamafile.getvalue().Java: l'esempio di codice Java per scaricare un file blob utilizza un
java.io.ByteArrayOutputStreamper acquisire i byte scaricati in memoria. UtilizzaoutputStream.toByteArray()per accedere all'array di byte non elaborati..NET: l'esempio di codice C# per scaricare un file blob utilizza un
System.IO.MemoryStream. Utilizzastream.ToArray()per accedere all'array di byte sottostante.Apps Script: l'esempio di codice Apps Script per scaricare un file blob utilizza un metodo
response.getBlob()per restituire un oggettoBlob. Converti questo valore in un array di byte utilizzando il metodogetBytes().
Download parziale
Il download parziale prevede il download solo di una parte specificata di un file. Puoi
specificare la porzione del file che vuoi scaricare utilizzando un intervallo
di byte con l'intestazione
Range. Ad esempio:
Range: bytes=500-999
Scaricare i contenuti del file blob in una versione precedente
Per scaricare il contenuto dei file blob in una versione precedente, utilizza il metodo
revisions.get con l'ID del file da scaricare, l'ID della revisione e il alt parametro
di sistema.
Il parametro alt=media indica al server che è stato richiesto il download dei contenuti come formato di risposta alternativo. Analogamente a files.get, il metodo revisions.get accetta anche il parametro di query acknowledgeAbuse e l'intestazione Range.
Puoi scaricare solo le revisioni dei contenuti dei file blob contrassegnate come "Conserva per sempre". Se vuoi scaricare una revisione, impostala prima su "Conserva per sempre". Per saperne di più, vedi Specificare le revisioni da salvare dall'eliminazione automatica.
Per ulteriori informazioni sul download di una revisione, consulta Gestire le operazioni a lunga esecuzione.
curl
curl -L "https://www.googleapis.com/drive/v3/files/FILE_ID/revisions/REVISION_ID?alt=media" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--output "FILE_NAME"
Sostituisci quanto segue:
- FILE_ID: l'ID del file da scaricare.
- REVISION_ID: l'ID della revisione da scaricare.
- ACCESS_TOKEN: il token di accesso che concede l'accesso all'API.
- FILE_NAME: il nome del file di output.
Scaricare i contenuti del file blob in un browser
Per scaricare il contenuto dei file blob archiviati su Drive all'interno di un browser, anziché tramite l'API, utilizza il campo webContentLink della risorsa files. Se l'utente ha accesso al download del file,
viene restituito un link per scaricare il file e i relativi contenuti. Puoi reindirizzare un utente a questo URL o offrirlo come link selezionabile.
curl
curl "https://www.googleapis.com/drive/v3/files/FILE_ID?fields=webContentLink" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Accept: application/json"
Sostituisci quanto segue:
- FILE_ID: l'ID del file per cui ottenere il link di download.
- ACCESS_TOKEN: il token di accesso che concede l'accesso all'API.
Scaricare i contenuti del file blob utilizzando operazioni a lunga esecuzione
Per scaricare i contenuti dei file blob utilizzando operazioni a lunga esecuzione (LRO), utilizza
il metodo files.download con l'ID del
file da scaricare. Puoi impostare facoltativamente l'ID della revisione.
Questo è l'unico modo per scaricare i file di Google Vids. Se tenti di esportare
file di Google Vids, ricevi un
errore fileNotExportable.
Per saperne di più, consulta Gestire le operazioni a lunga esecuzione.
curl
Il seguente comando curl avvia un'operazione LRO e restituisce una risposta JSON. Per scaricare il file o eseguire il polling di questa operazione LRO, devi effettuare un'altra richiesta utilizzando l'ID restituito per ottenere l'URL dei contenuti. Dopodiché, puoi effettuare una richiesta curl finale a quell'URL per scaricare il file. Per saperne di più, consulta Gestire le operazioni a lunga esecuzione.
curl --request POST "https://www.googleapis.com/drive/v3/files/FILE_ID/download?mimeType=video/mp4" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Content-Length: 0" \
--header "Accept: application/json"
Sostituisci quanto segue:
- FILE_ID: l'ID del file da scaricare.
- ACCESS_TOKEN: il token di accesso che concede l'accesso all'API.
Esportare i contenuti dei documenti Google Workspace
Per esportare il contenuto in byte del documento di Google Workspace, utilizzarefiles.export metodo con l'ID del file da esportare e il tipo MIME corretto. I contenuti esportati sono limitati a 10 MB.
Gli esempi di codice seguenti mostrano come utilizzare il metodo files.export per esportare un documento Google Workspace in formato PDF:
Apps Script
/**
* Exports a Google Workspace document.
* @param {string} fileId The ID of the file to export.
* @param {string} mimeType The MIME type to export to.
* @return {Blob} The exported content as a Blob.
*/
function exportPdf(fileId, mimeType) {
var url = 'https://www.googleapis.com/drive/v3/files/' + fileId + '/export?mimeType=' + encodeURIComponent(mimeType);
var response = UrlFetchApp.fetch(url, {
headers: {
'Authorization': 'Bearer ' + ScriptApp.getOAuthToken()
}
});
return response.getBlob();
}
Java
Python
Node.js
PHP
.NET
curl
curl -L "https://www.googleapis.com/drive/v3/files/FILE_ID/export?mimeType=application/pdf" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--output "FILE_NAME.pdf"
Sostituisci quanto segue:
- FILE_ID: l'ID del file da scaricare.
- ACCESS_TOKEN: il token di accesso che concede l'accesso all'API.
- FILE_NAME: il nome del file di output.
Gli esempi di codice della libreria client utilizzano l'ambito drive con limitazioni che consente
agli utenti di visualizzare e gestire tutti i tuoi file di Drive. Per saperne di più
sugli ambiti di Drive, consulta Scegliere gli ambiti dell'API Google Drive.
Gli esempi di codice dichiarano anche il tipo MIME di esportazione come application/pdf. Per un elenco completo di tutti i tipi MIME di esportazione supportati per ogni documento Google Workspace, consulta Tipi MIME di esportazione per i documenti Google Workspace.
Esportare i contenuti di un documento Google Workspace in un browser
Per esportare i contenuti dei documenti Google Workspace all'interno di un browser, utilizza il campo
exportLinks della risorsa
files. A seconda del tipo di documento, per ogni tipo MIME disponibile viene restituito un
link per scaricare il file e i relativi contenuti. Puoi reindirizzare un utente a un URL o offrirlo come link
su cui è possibile fare clic.
curl
curl "https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,exportLinks" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Accept: application/json"
Sostituisci quanto segue:
- FILE_ID: l'ID del file per cui ottenere il link di download.
- ACCESS_TOKEN: il token di accesso che concede l'accesso all'API.
Esportare i contenuti di un documento Google Workspace in una versione precedente in un browser
Per esportare i contenuti dei documenti Google Workspace in una versione precedente all'interno di un browser, utilizza il metodo revisions.get con l'ID del file da scaricare e l'ID della revisione per generare un link di esportazione da cui puoi eseguire il download. Se l'utente ha accesso al download del file, viene restituito un link per scaricare il file e i relativi contenuti. Puoi
reindirizzare un utente a questo URL o offrirlo come link su cui è possibile fare clic.
curl
curl "https://www.googleapis.com/drive/v3/files/FILE_ID/revisions/REVISION_ID?fields=id,name,exportLinks" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Accept: application/json"
Sostituisci quanto segue:
- FILE_ID: l'ID del file da scaricare.
- REVISION_ID: l'ID della revisione da scaricare.
- ACCESS_TOKEN: il token di accesso che concede l'accesso all'API.
Esportare i contenuti dei documenti Google Workspace utilizzando operazioni di lunga durata
Per esportare i contenuti dei documenti Google Workspace utilizzando operazioni di lunga durata (LRO), utilizza il metodo files.download con l'ID del file da scaricare e l'ID della revisione. Per saperne di più,
consulta Gestire le operazioni a lunga esecuzione.
curl
Il seguente comando curl avvia un'operazione LRO e restituisce una risposta JSON. Per scaricare il file o eseguire il polling di questa operazione LRO, devi effettuare un'altra richiesta utilizzando l'ID restituito per ottenere l'URL dei contenuti. Dopodiché, puoi effettuare una richiesta curl finale a quell'URL per scaricare il file. Per saperne di più, consulta Gestire le operazioni a lunga esecuzione.
curl --request POST "https://www.googleapis.com/drive/v3/files/FILE_ID/download?mimeType=MIME_TYPE&revisionId=REVISION_ID" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Content-Length: 0" \
--header "Accept: application/json"
Sostituisci quanto segue:
- FILE_ID: l'ID del file da scaricare.
- MIME_TYPE: il tipo MIME in cui esportare.
- REVISION_ID: l'ID della revisione da scaricare.
- ACCESS_TOKEN: il token di accesso che concede l'accesso all'API.