Mit der Google Drive API können Sie Dateidaten hochladen, wenn Sie einen File
erstellen oder aktualisieren. Informationen zum Erstellen eines reinen Metadaten-File
finden Sie unter Dateien erstellen.
Es gibt drei Arten von Uploads:
Einfacher Upload (
uploadType=media
): Mit diesem Uploadtyp können Sie eine kleine Mediendatei (maximal 5 MB) ohne Metadaten übertragen. Informationen zum Durchführen eines einfachen Uploads finden Sie unter Einfachen Upload durchführen.Mehrteiliger Upload (
uploadType=multipart
): Mit diesem Uploadtyp können Sie eine kleine Datei (maximal 5 MB) zusammen mit Metadaten, die die Datei beschreiben, in einer einzigen Anfrage übertragen. Informationen zum Ausführen eines mehrteiligen Uploads finden Sie unter Mehrteiligen Upload durchführen.Fortsetzbarer Upload (
uploadType=resumable
): Verwenden Sie diesen Uploadtyp für große Dateien (über 5 MB) und wenn die Wahrscheinlichkeit einer Netzwerkunterbrechung sehr hoch ist, z. B. beim Erstellen einer Datei von einer mobilen App. Fortsetzbare Uploads sind außerdem eine gute Wahl für die meisten Anwendungen, da sie auch für kleine Dateien funktionieren – und zwar zu minimalen Kosten von einer zusätzlichen HTTP-Anfrage pro Upload. Informationen zum Ausführen eines fortsetzbaren Uploads finden Sie unter Fortsetzbare Uploads ausführen.
Die Google API-Clientbibliotheken implementieren mindestens einen dieser Uploadtypen. Weitere Informationen zur Verwendung der einzelnen Typen finden Sie in der Dokumentation zur Clientbibliothek.
PATCH
vs. PUT
verwenden
Zur Erinnerung: Das HTTP-Verb PATCH
unterstützt eine teilweise Aktualisierung von Dateiressourcen, während das HTTP-Verb PUT
vollständige Ressourcenersetzung unterstützt. Beachten Sie, dass PUT
zu funktionsgefährdenden Änderungen führen kann, wenn einer vorhandenen Ressource ein neues Feld hinzugefügt wird.
Beachten Sie beim Hochladen einer Dateiressource die folgenden Richtlinien:
- Verwenden Sie das in der API-Referenz dokumentierte HTTP-Verb für die erste Anfrage eines fortsetzbaren Uploads oder für die einzige Anfrage eines einfachen oder mehrteiligen Uploads.
- Verwenden Sie
PUT
für alle nachfolgenden Anfragen für einen fortsetzbaren Upload, nachdem die Anfrage gestartet wurde. Mit diesen Anfragen werden Inhalte unabhängig von der aufgerufenen Methode hochgeladen.
Einfachen Upload durchführen
Für einen einfachen Upload verwenden Sie die Methode files.create mit uploadType=media
.
Im Folgenden wird gezeigt, wie Sie einen einfachen Upload durchführen:
HTTP
Erstellen Sie eine
POST
-Anfrage an den /upload-URI der Methode mit dem AbfrageparameteruploadType=media
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media
Fügen Sie die Daten der Datei in den Anfragetext ein.
Fügen Sie diese HTTP-Header hinzu:
Content-Type
: Legen Sie als Wert den MIME-Medientyp des hochgeladenen Objekts fest.Content-Length
. Legen Sie als Wert die Anzahl von Bytes fest, die Sie hochladen. Wenn Sie die aufgeteilte Transferverschlüsselung verwenden, ist dieser Header nicht erforderlich.
Senden Sie die Anfrage. Wenn die Anfrage erfolgreich ist, gibt der Server den Statuscode
HTTP 200 OK
zusammen mit den Metadaten der Datei zurück. {HTTP}
Wenn Sie einen einfachen Upload durchführen, werden grundlegende Metadaten erstellt und aus der Datei werden einige Attribute abgeleitet, z. B. der MIME-Typ oder modifiedTime
. Sie können einen einfachen Upload verwenden, wenn Sie kleine Dateien haben und Dateimetadaten nicht wichtig sind.
Mehrteiligen Upload durchführen
Mit einer mehrteiligen Uploadanfrage können Sie Metadaten und Daten in derselben Anfrage hochladen. Verwenden Sie diese Option, wenn die gesendeten Daten klein genug sind, um sie bei einem Verbindungsfehler noch einmal vollständig hochzuladen.
Für einen mehrteiligen Upload verwenden Sie die Methode files.create mit uploadType=multipart
.
So führen Sie einen mehrteiligen Upload durch:
Java
Python
Node.js
PHP
.NET
HTTP
Erstellen Sie eine
POST
-Anfrage an den /upload-URI der Methode mit dem AbfrageparameteruploadType=multipart
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
Erstellen Sie den Hauptteil der Anfrage. Formatieren Sie den Text gemäß dem Datentyp „Multipart/related content“ [RFC 2387], der aus zwei Teilen besteht:
- Metadaten: Die Metadaten müssen an erster Stelle stehen und der Header
Content-Type
muss aufapplication/json;
charset=UTF-8
festgelegt sein. Fügen Sie die Metadaten der Datei im JSON-Format hinzu. - Medien. Das Medium muss an zweiter Stelle stehen und einen
Content-Type
-Header eines beliebigen MIME-Typs haben. Fügen Sie die Daten der Datei dem Medienteil hinzu.
Identifizieren Sie jeden Teil mit einem Grenzstring, dem zwei Bindestriche vorangestellt sind. Fügen Sie außerdem nach dem letzten Grenzstring zwei Bindestriche hinzu.
- Metadaten: Die Metadaten müssen an erster Stelle stehen und der Header
Fügen Sie diese Top-Level-HTTP-Header hinzu:
Content-Type
. Legen Sie dafürmultipart/related
fest und fügen Sie den Grenzstring ein, mit dem Sie die verschiedenen Teile der Anfrage identifizieren. Beispiel:Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length
. Setzen Sie den Wert auf die Gesamtanzahl von Byte im Anfragetext.
Senden Sie die Anfrage.
Wenn Sie nur den Metadatenteil ohne die zugehörigen Daten erstellen oder aktualisieren möchten, senden Sie eine POST
- oder PATCH
-Anfrage an den Standardressourcenendpunkt: https://www.googleapis.com/drive/v3/files
. Wenn die Anfrage erfolgreich ist, gibt der Server den Statuscode HTTP 200 OK
zusammen mit den Metadaten der Datei zurück.
Beim Erstellen von Dateien sollten sie eine Dateiendung im Feld name
der Datei angeben. Wenn Sie beispielsweise eine JPEG-Fotodatei erstellen, können Sie in den Metadaten "name": "photo.jpg"
angeben. Bei nachfolgenden Aufrufen von files.get wird das schreibgeschützte Attribut fileExtension
zurückgegeben, das die ursprünglich im Feld name
angegebene Erweiterung enthält.
Fortsetzbaren Upload durchführen
Mit einem fortsetzbaren Upload können Sie einen Uploadvorgang fortsetzen, nachdem ein Kommunikationsfehler den Datenfluss unterbrochen hat. Da Sie große Dateiuploads nicht von Anfang an neu starten müssen, können fortsetzbare Uploads auch Ihre Bandbreitennutzung bei einem Netzwerkfehler reduzieren.
Fortsetzbare Uploads sind nützlich, wenn Ihre Dateigrößen stark variieren können oder wenn es ein festes Zeitlimit für Anfragen gibt (z. B. Hintergrundaufgaben des mobilen Betriebssystems und bestimmte App Engine-Anfragen). Fortsetzbare Uploads eignen sich auch, wenn eine Fortschrittsanzeige für den Upload angezeigt werden soll.
Ein fortsetzbarer Upload umfasst mehrere allgemeine Schritte:
- Senden Sie die erste Anfrage und rufen Sie den URI der fortsetzbaren Sitzung ab.
- Laden Sie die Daten hoch und überwachen Sie den Uploadstatus.
- Optional: Wenn der Upload unterbrochen wird, setzen Sie ihn fort.
Erste Anfrage senden
Verwenden Sie die Methode files.create mit uploadType=resumable
, um einen fortsetzbaren Upload zu starten.
HTTP
Erstellen Sie eine
POST
-Anfrage an den /upload-URI der Methode mit dem AbfrageparameteruploadType=resumable
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable
Wenn die Initiierungsanfrage erfolgreich ist, enthält die Antwort den HTTP-Statuscode
200 OK
. Darüber hinaus enthält er einenLocation
-Header, der den URI der fortsetzbaren Sitzung angibt:HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0
Speichern Sie den URI der fortsetzbaren Sitzung, damit Sie die Dateidaten hochladen und den Uploadstatus abfragen können. Der URI einer fortsetzbaren Sitzung läuft nach einer Woche ab.
Wenn Metadaten für die Datei vorhanden sind, fügen Sie sie dem Anfragetext im JSON-Format hinzu. Ansonsten lassen Sie den Anfragetext leer.
Fügen Sie diese HTTP-Header hinzu:
X-Upload-Content-Type
. Optional. Legen Sie als Wert den MIME-Typ der Dateidaten fest, die in nachfolgenden Anfragen übertragen werden. Wenn der MIME-Typ der Daten nicht in den Metadaten oder über diesen Header angegeben ist, wird das Objekt alsapplication/octet-stream.
bereitgestellt.X-Upload-Content-Length
. Optional. Legen Sie als Wert die Anzahl von Bytes der Dateidaten fest, die in nachfolgenden Anfragen übertragen werden.Content-Type
. Dies ist erforderlich, wenn Sie Metadaten für die Datei haben. Legen Sie dafürapplication/json;
charset=UTF-8
fest.Content-Length
. Erforderlich, es sei denn, Sie verwenden die aufgeteilte Transfercodierung. Legen Sie als Wert die Anzahl von Byte im Text dieser ersten Anfrage fest.
Senden Sie die Anfrage. Wenn die Anfrage zum Starten der Sitzung erfolgreich ist, enthält die Antwort den Statuscode
200 OK HTTP
. Darüber hinaus enthält die Antwort einenLocation
-Header, der den URI der fortsetzbaren Sitzung angibt. Verwenden Sie den URI der fortsetzbaren Sitzung, um die Dateidaten hochzuladen und den Uploadstatus abzufragen. Der URI einer fortsetzbaren Sitzung läuft nach einer Woche ab.Kopieren und speichern Sie die URL der fortsetzbaren Sitzung.
Fahren Sie mit dem Schritt Inhalte hochladen fort.
Inhalt hochladen
Es gibt zwei Möglichkeiten, eine Datei mit einer fortsetzbaren Sitzung hochzuladen:
- Inhalte in einer einzelnen Anfrage hochladen: Verwenden Sie diesen Ansatz, wenn die Datei in einer Anfrage hochgeladen werden kann, es kein festes Zeitlimit für eine einzelne Anfrage gibt oder keine Fortschrittsanzeige für den Upload erforderlich ist. Dieser Ansatz ist am besten geeignet, da er weniger Anfragen erfordert und zu einer besseren Leistung führt.
Den Inhalt in mehreren Blöcken hochladen: Verwenden Sie diesen Ansatz, wenn Sie die in einer einzelnen Anfrage übertragene Datenmenge reduzieren müssen. Möglicherweise müssen Sie die übertragenen Daten reduzieren, wenn für einzelne Anfragen ein festes Zeitlimit gilt, wie es bei bestimmten Klassen von App Engine-Anfragen der Fall sein kann. Dieser Ansatz ist auch nützlich, wenn Sie einen benutzerdefinierten Indikator zur Anzeige des Uploadfortschritts bereitstellen müssen.
HTTP – Einzelanfrage
- Erstellen Sie eine
PUT
-Anfrage an den URI der fortsetzbaren Sitzung. - Fügen Sie die Daten der Datei in den Anfragetext ein.
- Fügen Sie einen Content-Length-HTTP-Header hinzu, der auf die Anzahl von Byte in der Datei festgelegt ist.
- Senden Sie die Anfrage. Wenn die Uploadanfrage unterbrochen wird oder Sie eine
5xx
-Antwort erhalten, folgen Sie der Anleitung unter Unterbrochenen Upload fortsetzen.
HTTP – mehrere Anfragen
Erstellen Sie eine
PUT
-Anfrage an den URI der fortsetzbaren Sitzung.Fügen Sie die Daten des Teils in den Anfragetext ein. Erstellen Sie Blöcke in Vielfachen von 256 KB (256 x 1024 Byte), mit Ausnahme des letzten Blocks, der den Upload abschließt. Halten Sie die Chunk-Größe so groß wie möglich, damit der Upload effizient ist.
Fügen Sie diese HTTP-Header hinzu:
Content-Length
. Legen Sie als Wert die Anzahl von Bytes im aktuellen Teil fest.Content-Range
. Legen Sie fest, dass angezeigt werden soll, welche Byte in der Datei hochgeladen werden.Content-Range: bytes 0-524287/2000000
gibt beispielsweise an, dass Sie die ersten 524.288 Byte (256 × 1024 × 2) in einer Datei mit 2.000.000 Byte hochladen.
Senden Sie die Anfrage und verarbeiten Sie die Antwort. Wenn die Uploadanfrage unterbrochen wird oder Sie eine
5xx
-Antwort erhalten, folgen Sie der Anleitung unter Unterbrochenen Upload fortsetzen.Wiederholen Sie die Schritte 1 bis 4 für jeden Teil der Datei. Verwenden Sie den Header
Range
in der Antwort, um zu ermitteln, wo der nächste Chunk beginnen soll. Gehen Sie nicht davon aus, dass der Server alle Byte erhalten hat, die in der vorherigen Anfrage gesendet wurden.
Wenn der gesamte Dateiupload abgeschlossen ist, erhalten Sie die Antwort 200 OK
oder 201 Created
zusammen mit allen Metadaten, die der Ressource zugeordnet sind.
Unterbrochenen Upload fortsetzen
Wenn eine Uploadanfrage vor einer Antwort beendet wird oder Sie eine 503 Service Unavailable
-Antwort erhalten, müssen Sie den unterbrochenen Upload fortsetzen.
HTTP
Zum Anfordern des Uploadstatus erstellen Sie eine leere
PUT
-Anfrage an den URI der fortsetzbaren Sitzung.Fügen Sie einen
Content-Range
-Header hinzu, um anzugeben, dass die aktuelle Position in der Datei unbekannt ist. Legen Sie beispielsweiseContent-Range
auf*/2000000
fest, wenn die Gesamtdateilänge 2.000.000 Byte beträgt. Wenn Sie die Gesamtgröße der Datei nicht kennen, legen SieContent-Range
auf*/*
fest.Senden Sie die Anfrage.
Verarbeiten Sie die Antwort:
- Eine
200 OK
- oder201 Created
-Antwort gibt an, dass der Upload abgeschlossen wurde und keine weiteren Maßnahmen erforderlich sind. - Die Antwort
308 Resume Incomplete
gibt an, dass Sie mit dem Hochladen der Datei fortfahren müssen. - Die Antwort
404 Not Found
gibt an, dass die Uploadsitzung abgelaufen ist und der Upload von Anfang an neu gestartet werden muss.
- Eine
Wenn Sie eine
308 Resume Incomplete
-Antwort erhalten haben, verarbeiten Sie denRange
-Header der Antwort, um festzustellen, welche Byte der Server empfangen hat. Wenn die Antwort keinenRange
-Header hat, wurden keine Bytes empfangen. EinRange
-Header mit dem Wertbytes=0-42
gibt beispielsweise an, dass die ersten 43 Byte der Datei empfangen wurden und dass der nächste hochzuladende Block mit Byte 44 beginnen würde.Nachdem Sie nun wissen, wo Sie den Upload fortsetzen sollen, fahren Sie mit dem Hochladen der Datei fort, beginnend mit dem nächsten Byte. Fügen Sie den Header
Content-Range
ein, um anzugeben, welchen Teil der Datei Sie senden.Content-Range: bytes 43-1999999
gibt beispielsweise an, dass Sie die Byte 44 bis 2.000.000 senden.
Fehler beim Hochladen von Medien beheben
Halten Sie sich beim Hochladen von Medien an die folgenden Best Practices, um Fehler zu beheben:
- Setzen Sie bei
5xx
-Fehlern Uploads fort oder wiederholen Sie sie, die aufgrund von Verbindungsunterbrechungen fehlschlagen. Weitere Informationen zum Umgang mit5xx
-Fehlern finden Sie unter5xx
-Fehler beheben. - Wiederholen Sie den Upload bei
403 rate limit
Fehlern. Weitere Informationen zum Umgang mit403 rate limit
-Fehlern finden Sie unter403 error: Rate limit exceeded
beheben. - Wenn während eines fortsetzbaren Uploads
4xx
-Fehler (einschließlich403
) auftreten, starten Sie den Upload neu. Diese Fehler weisen darauf hin, dass die Uploadsitzung abgelaufen ist und neu gestartet werden muss, indem Sie einen neuen Sitzungs-URI anfordern. Upload-Sitzungen laufen auch nach einer Woche Inaktivität ab.
In Google Docs-Typen importieren
Wenn Sie eine Datei in Drive erstellen, können Sie sie in einen Google Workspace-Dateityp konvertieren, z. B. in ein Google-Dokument oder eine Google-Tabelle. Vielleicht möchten Sie z. B. ein Dokument aus Ihrem bevorzugten Textverarbeitungsprogramm in ein Google-Dokument konvertieren, um die Funktionen nutzen zu können.
Wenn Sie eine Datei in einen bestimmten Google Workspace-Dateityp konvertieren möchten, geben Sie beim Erstellen der Datei die Google Workspace-mimeType
an.
Im Folgenden wird gezeigt, wie Sie eine CSV-Datei in eine Google Workspace-Tabelle konvertieren:
Java
Python
Node.js
PHP
.NET
Prüfen Sie vor dem Erstellen der Datei das importFormats
-Array der Info-Ressource, um festzustellen, ob eine Konvertierung verfügbar ist. Die unterstützten Conversions sind in diesem Array dynamisch verfügbar. Gängige Importformate:
From | Bis |
---|---|
Microsoft Word, OpenDocument Text, HTML, RTF, Nur-Text | Google Docs |
Microsoft Excel, OpenDocument-Tabelle, CSV, TSV, Nur-Text | Google Tabellen |
Microsoft PowerPoint, OpenDocument-Präsentation | Google Präsentationen |
JPEG, PNG, GIF, BMP, PDF | Google Docs (bettet das Bild in ein Dokument ein) |
Nur-Text (spezieller MIME-Typ), JSON | Google Apps Script |
Wenn Sie Medien während einer update
-Anfrage in ein Google-Dokument, eine Google-Tabelle oder eine Google-Präsentation hochladen und konvertieren, wird der gesamte Inhalt des Dokuments ersetzt.
Wenn Sie ein Bild in ein Dokument konvertieren, verwendet Drive die optische Zeichenerkennung (Optical Character Recognition, OCR), um das Bild in Text zu konvertieren. Sie können die Qualität des OCR-Algorithmus verbessern, indem Sie den entsprechenden BCP 47-Sprachcode im Parameter ocrLanguage
angeben.
Der extrahierte Text wird im Dokument neben dem eingebetteten Bild angezeigt.
Vorgefertigte ID zum Hochladen von Dateien verwenden
Mit der Drive API können Sie eine Liste vorgenerierter Datei-IDs abrufen, die zum Hochladen und Erstellen von Ressourcen verwendet werden. Bei Anfragen zum Hochladen und Erstellen von Dateien können diese vorab generierten IDs verwendet werden. Legen Sie das Feld id
in den Dateimetadaten fest.
Um vorab generierte IDs zu erstellen, rufen Sie file.generateIds mit der Anzahl der zu erstellenden IDs auf.
Sie können Uploads mit vorab generierten IDs bedenkenlos wiederholen, wenn ein unbestimmter Serverfehler oder eine Zeitüberschreitung auftritt. Wenn die Datei erfolgreich erstellt wurde, wird bei nachfolgenden Wiederholungsversuchen der Fehler HTTP 409
zurückgegeben und es werden keine doppelten Dateien erstellt.
Indexierbaren Text für unbekannte Dateitypen definieren
Nutzer können die Drive-Benutzeroberfläche verwenden, um nach Dokumentinhalten zu suchen. Sie können auch files.list und das Feld fullText
verwenden, um nach Inhalten in Ihrer Anwendung zu suchen. Weitere Informationen finden Sie unter Nach Dateien und Ordnern suchen.
Drive indexiert Dokumente automatisch für die Suche, wenn der Dateityp erkannt wird, darunter Textdokumente, PDFs, Bilder mit Text und andere gängige Typen. Wenn Ihre Anwendung andere Dateitypen speichert (z. B. Zeichnungen, Videos und Verknüpfungen), können Sie die Sichtbarkeit verbessern. Geben Sie dazu in das Feld contentHints.indexableText
der Datei indexierbaren Text an.
Weitere Informationen zu indexierbaren Texten finden Sie unter Dateimetadaten verwalten.