Die Google Drive API unterstützt verschiedene Arten von Download- und Exportvorgängen, die in der folgenden Tabelle aufgeführt sind:
| Download-Aktionen |
|
||||
| Exportaktionen |
|
In der Drive API bezieht sich eine Blob-Datei auf eine beliebige Binärdatei, die in Google Drive gespeichert ist, z. B. Bilder, Videos und PDFs, im Gegensatz zu einem Google Workspace-Dokument. Es bezieht sich nicht auf das Blob-Objekt von JavaScript. Detaillierte Beschreibungen der hier erwähnten Dateitypen, einschließlich Blob- und Google Workspace-Dateien, finden Sie unter Dateitypen.
Bevor Sie Dateiinhalte herunterladen oder exportieren, prüfen Sie, ob Nutzer die Datei über das Feld capabilities.canDownload in der Ressource files herunterladen können.
Im restlichen Teil dieses Dokuments finden Sie eine detaillierte Anleitung zum Ausführen dieser Arten von Download- und Exportvorgängen.
Blob-Dateiinhalt herunterladen
Wenn Sie eine in Drive gespeicherte Blob-Datei herunterladen möchten, verwenden Sie die Methode files.get mit der ID der herunterzuladenden Datei und dem alt-Systemparameter.
Mit dem Parameter alt=media wird dem Server mitgeteilt, dass ein Download von Inhalten als alternatives Antwortformat angefordert wird.
Der Systemparameter alt ist in allen Google REST APIs verfügbar. Wenn Sie eine Drive API-Clientbibliothek verwenden, müssen Sie diesen Parameter nicht explizit festlegen, da die Clientbibliotheksmethode den Parameter alt=media der zugrunde liegenden HTTP-Anfrage hinzufügt.
Die folgenden Codebeispiele zeigen, wie Sie die Methode files.get verwenden, um eine Datei herunterzuladen:
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"
Ersetzen Sie Folgendes:
- FILE_ID: Die ID der herunterzuladenden Datei.
- ACCESS_TOKEN: Das Zugriffstoken, das den Zugriff auf die API gewährt.
- FILE_NAME: Der Name der Ausgabedatei.
Dateidownloads, die von Ihrer App gestartet werden, müssen mit einem Bereich autorisiert werden, der Lesezugriff auf den Dateiinhalt ermöglicht. Eine App, die den Bereich drive.readonly.metadata verwendet, ist beispielsweise nicht berechtigt, die Dateiinhalte herunterzuladen.
In den Codebeispielen für Clientbibliotheken wird der eingeschränkte Dateibereich drive verwendet, mit dem Nutzer alle Ihre Drive-Dateien ansehen und verwalten können. Weitere Informationen zu Drive-Bereichen finden Sie unter Google Drive API-Bereiche auswählen.
Nutzer mit owner-Berechtigungen (für Dateien in „Meine Ablage“) oder organizer-Berechtigungen (für Dateien in geteilten Ablagen) können das Herunterladen über das DownloadRestrictionsMetadata-Objekt einschränken. Weitere Informationen finden Sie unter Herunterladen, Drucken oder Kopieren von Dateien verhindern.
Dateien, die als missbräuchlich (z. B. schädliche Software) identifiziert wurden, können nur vom Dateieigentümer heruntergeladen werden.
Außerdem muss der Abfrageparameter acknowledgeAbuse auf true gesetzt werden, um anzugeben, dass der Nutzer das Risiko des Herunterladens potenziell unerwünschter Software oder anderer missbräuchlicher Dateien zur Kenntnis genommen hat. Ihre Anwendung sollte den Nutzer interaktiv warnen, bevor dieser Abfrageparameter verwendet wird.
Auf Dateidaten im Arbeitsspeicher zugreifen
Wenn Ihre Anwendung direkt im Arbeitsspeicher auf die Dateidaten zugreifen muss (z. B. als Bytepuffer), anstatt sie auf einer lokalen Festplatte zu speichern, können Sie die Clientbibliotheksanfrage anpassen oder den zurückgegebenen Stream verarbeiten:
Node.js: Standardmäßig gibt die Node.js-Clientbibliothek den Dateiinhalt als
Readable-Stream zurück. So speichern Sie die Datei auf der lokalen Festplatte: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);Alternativ können Sie die Daten direkt im Arbeitsspeicher als
ArrayBufferanstelle eines Streams zurückgeben lassen. Dazu legen Sie den ParameterresponseTypein Ihren Anforderungsoptionen fest: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: Im Python-Codebeispiel zum Herunterladen einer Blob-Datei werden die Download-Chunks bereits in ein
io.BytesIO()-Objekt im Arbeitsspeicher geschrieben. Rufen Siefile.getvalue()auf, um auf die Rohbytes zuzugreifen.Java: Das Java-Codebeispiel zum Herunterladen einer Blob-Datei verwendet ein
java.io.ByteArrayOutputStream, um die heruntergeladenen Byte im Arbeitsspeicher zu erfassen. Verwenden SieoutputStream.toByteArray(), um auf das Rohbyte-Array zuzugreifen..NET: Im C#-Codebeispiel zum Herunterladen einer Blobdatei wird ein
System.IO.MemoryStreamverwendet. Verwenden Siestream.ToArray(), um auf das zugrunde liegende Byte-Array zuzugreifen.Apps Script: Im Apps Script-Codebeispiel zum Herunterladen einer Blob-Datei wird eine
response.getBlob()-Methode verwendet, um einBlob-Objekt zurückzugeben. Wandeln Sie dies mit der MethodegetBytes()in ein Byte-Array um.
Teilweiser Download
Beim partiellen Download wird nur ein bestimmter Teil einer Datei heruntergeladen. Sie können den Teil der Datei, den Sie herunterladen möchten, mit einem Bytebereich im Header Range angeben. Beispiel:
Range: bytes=500-999
Blob-Dateiinhalt in einer früheren Version herunterladen
Wenn Sie den Inhalt von Blob-Dateien in einer früheren Version herunterladen möchten, verwenden Sie die Methode revisions.get mit der ID der herunterzuladenden Datei, der ID der Revision und dem alt-Systemparameter.
Mit dem Parameter alt=media wird dem Server mitgeteilt, dass ein Download von Inhalten als alternatives Antwortformat angefordert wird. Ähnlich wie bei files.get akzeptiert die Methode revisions.get auch den Abfrageparameter acknowledgeAbuse und den Header Range.
Sie können nur Blob-Dateiinhaltsrevisionen herunterladen, die als „Niemals löschen“ gekennzeichnet sind. Wenn Sie eine Version herunterladen möchten, müssen Sie sie zuerst auf „Niemals löschen“ setzen. Weitere Informationen finden Sie unter Revisionen angeben, die nicht automatisch gelöscht werden sollen.
Weitere Informationen zum Herunterladen einer Überarbeitung finden Sie unter Vorgänge mit langer Ausführungszeit verwalten.
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"
Ersetzen Sie Folgendes:
- FILE_ID: Die ID der herunterzuladenden Datei.
- REVISION_ID: Die ID der herunterzuladenden Überarbeitung.
- ACCESS_TOKEN: Das Zugriffstoken, das den Zugriff auf die API gewährt.
- FILE_NAME: Der Name der Ausgabedatei.
Blob-Dateiinhalt in einem Browser herunterladen
Wenn Sie den Inhalt von Blob-Dateien, die in Drive gespeichert sind, in einem Browser anstatt über die API herunterladen möchten, verwenden Sie das Feld webContentLink der Ressource files. Wenn der Nutzer Downloadzugriff auf die Datei hat, wird ein Link zum Herunterladen der Datei und ihrer Inhalte zurückgegeben. Sie können einen Nutzer entweder zu dieser URL weiterleiten oder sie als klickbaren Link anbieten.
curl
curl "https://www.googleapis.com/drive/v3/files/FILE_ID?fields=webContentLink" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Accept: application/json"
Ersetzen Sie Folgendes:
- FILE_ID: die ID der Datei, für die der Downloadlink abgerufen werden soll.
- ACCESS_TOKEN: Das Zugriffstoken, das den Zugriff auf die API gewährt.
Blob-Dateiinhalte mit lang andauernden Vorgängen herunterladen
Wenn Sie den Inhalt von Blob-Dateien mit Vorgängen mit langer Ausführungszeit (Long-Running Operations, LRO) herunterladen möchten, verwenden Sie die Methode files.download mit der ID der herunterzuladenden Datei. Optional können Sie die ID der Überarbeitung festlegen.
Dies ist die einzige Möglichkeit, Google Vids-Dateien herunterzuladen. Wenn Sie versuchen, Google Vids-Dateien zu exportieren, wird der Fehler fileNotExportable angezeigt.
Weitere Informationen finden Sie unter Vorgänge mit langer Ausführungszeit verwalten.
curl
Mit dem folgenden curl-Befehl wird ein LRO initiiert und eine JSON-Antwort zurückgegeben. Wenn Sie die Datei herunterladen oder diesen LRO abfragen möchten, müssen Sie eine weitere Anfrage mit der zurückgegebenen ID senden, um die Content-URL zu erhalten. Anschließend können Sie eine letzte curl-Anfrage an diese URL senden, um die Datei herunterzuladen. Weitere Informationen finden Sie unter Vorgänge mit langer Laufzeit verwalten.
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"
Ersetzen Sie Folgendes:
- FILE_ID: Die ID der herunterzuladenden Datei.
- ACCESS_TOKEN: Das Zugriffstoken, das den Zugriff auf die API gewährt.
Inhalte von Google Workspace-Dokumenten exportieren
Wenn Sie Byte-Inhalte von Google Workspace-Dokumenten exportieren möchten, verwenden Sie die Methode files.export mit der ID der zu exportierenden Datei und dem richtigen MIME-Typ. Die exportierten Inhalte sind auf 10 MB begrenzt.
Die folgenden Codebeispiele zeigen, wie Sie die Methode files.export verwenden, um ein Google Workspace-Dokument im PDF-Format zu exportieren:
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"
Ersetzen Sie Folgendes:
- FILE_ID: Die ID der herunterzuladenden Datei.
- ACCESS_TOKEN: Das Zugriffstoken, das den Zugriff auf die API gewährt.
- FILE_NAME: Der Name der Ausgabedatei.
In den Codebeispielen für die Clientbibliothek wird der eingeschränkte Bereich drive verwendet, mit dem Nutzer alle Ihre Drive-Dateien ansehen und verwalten können. Weitere Informationen zu Drive-Bereichen finden Sie unter Google Drive API-Bereiche auswählen.
In den Codebeispielen wird der MIME-Typ für den Export auch als application/pdf deklariert. Eine vollständige Liste aller Export-MIME-Typen, die für die einzelnen Google Workspace-Dokumente unterstützt werden, finden Sie unter Export-MIME-Typen für Google Workspace-Dokumente.
Google Workspace-Dokumentinhalte in einem Browser exportieren
Wenn Sie Inhalte aus Google Workspace-Dokumenten in einem Browser exportieren möchten, verwenden Sie das Feld exportLinks der Ressource files. Je nach Dokumenttyp wird für jeden verfügbaren MIME-Typ ein Link zum Herunterladen der Datei und ihres Inhalts zurückgegeben. Sie können einen Nutzer entweder zu einer URL weiterleiten oder sie als anklickbaren Link anbieten.
curl
curl "https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,exportLinks" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Accept: application/json"
Ersetzen Sie Folgendes:
- FILE_ID: die ID der Datei, für die der Downloadlink abgerufen werden soll.
- ACCESS_TOKEN: Das Zugriffstoken, das den Zugriff auf die API gewährt.
Google Workspace-Dokumentinhalte in einer früheren Version in einem Browser exportieren
Wenn Sie Google Workspace-Dokumentinhalte in einer früheren Version in einem Browser exportieren möchten, verwenden Sie die Methode revisions.get mit der ID der herunterzuladenden Datei und der ID der Revision, um einen Exportlink zu generieren, über den Sie den Download ausführen können. Wenn der Nutzer Downloadzugriff auf die Datei hat, wird ein Link zum Herunterladen der Datei und ihres Inhalts zurückgegeben. Sie können einen Nutzer entweder zu dieser URL weiterleiten oder sie als klickbaren Link anbieten.
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"
Ersetzen Sie Folgendes:
- FILE_ID: Die ID der herunterzuladenden Datei.
- REVISION_ID: Die ID der herunterzuladenden Überarbeitung.
- ACCESS_TOKEN: Das Zugriffstoken, das den Zugriff auf die API gewährt.
Google Workspace-Dokumentinhalte mit zeitaufwendigen Vorgängen exportieren
Wenn Sie Google Workspace-Dokumentinhalte mit LROs (Long-Running Operations) exportieren möchten, verwenden Sie die Methode files.download mit der ID der herunterzuladenden Datei und der ID der Revision. Weitere Informationen finden Sie unter Vorgänge mit langer Laufzeit verwalten.
curl
Mit dem folgenden curl-Befehl wird ein LRO initiiert und eine JSON-Antwort zurückgegeben. Wenn Sie die Datei herunterladen oder diesen LRO abfragen möchten, müssen Sie eine weitere Anfrage mit der zurückgegebenen ID senden, um die Content-URL zu erhalten. Anschließend können Sie eine letzte curl-Anfrage an diese URL senden, um die Datei herunterzuladen. Weitere Informationen finden Sie unter Vorgänge mit langer Laufzeit verwalten.
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"
Ersetzen Sie Folgendes:
- FILE_ID: Die ID der herunterzuladenden Datei.
- MIME_TYPE: Der MIME-Typ, in den exportiert werden soll.
- REVISION_ID: Die ID der herunterzuladenden Überarbeitung.
- ACCESS_TOKEN: Das Zugriffstoken, das den Zugriff auf die API gewährt.