Mit der Google Drive API können Sie Dateidaten hochladen, wenn Sie eine File
erstellen oder aktualisieren. Informationen zum Erstellen einer Datei, die nur Metadaten enthält, z. B. eines Ordners, finden Sie unter Dateien erstellen, die nur Metadaten enthalten.
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 einfachen Upload finden Sie unter Einen einfachen Upload ausführen.Mehrere Uploads (
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 ausführen.Fortsetzbarer Upload (
uploadType=resumable
): Verwenden Sie diesen Uploadtyp für große Dateien (über 5 MB) und wenn eine hohe Wahrscheinlichkeit für Netzwerkunterbrechungen besteht, z. B. beim Erstellen einer Datei über eine mobile App. Fortsetzbare Uploads sind auch für die meisten Anwendungen eine gute Wahl, da sie zum Preis von nur einer zusätzlichen HTTP-Anfrage pro Upload auch für kleinere Dateien verwendet werden können. Informationen zum Durchführen eines fortsetzbaren Uploads finden Sie unter Fortsetzbaren Upload ausführen.
Die Google API-Clientbibliotheken implementieren mindestens eine dieser Uploadtypen. Weitere Informationen zur Verwendung der einzelnen Typen finden Sie in der Dokumentation zur Clientbibliothek.
PATCH
und PUT
vergleichen
Zur Wiederholung: Das HTTP-Verb PATCH
unterstützt eine teilweise Aktualisierung von Dateiressourcen, während das HTTP-Verb PUT
den vollständigen Austausch von Ressourcen unterstützt. Beachten Sie, dass PUT
möglicherweise zu bahnbrechenden Änderungen führt, wenn Sie einer vorhandenen Ressource ein neues Feld hinzufügen.
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, sobald die Anfrage gestartet wurde. Bei diesen Anfragen werden Inhalte unabhängig von der aufgerufenen Methode hochgeladen.
Einfachen Upload ausführen
Verwenden Sie die Methode files.create
mit uploadType=media
, um einen einfachen Upload durchzuführen.
Im Folgenden wird ein einfacher Upload veranschaulicht:
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 die folgenden HTTP-Header hinzu:
Content-Type
. Legen Sie als Wert den MIME-Medientyp des hochgeladenen Objekts fest.Content-Length
. Legen Sie als Wert die Anzahl der hochgeladenen Byte fest. Wenn Sie die Chunked Transfer Encoding verwenden, ist dieser Header nicht erforderlich.
Senden Sie die Anfrage. Ist die Anfrage erfolgreich, gibt der Server den Statuscode
HTTP 200 OK
zusammen mit den Metadaten der Datei zurück. {HTTP}
Bei einem einfachen Upload werden grundlegende Metadaten erstellt und einige Attribute werden aus der Datei abgeleitet, z. B. der MIME-Typ oder modifiedTime
. Sie können einen einfachen Upload verwenden, wenn Sie kleine Dateien haben und die Dateimetadaten nicht wichtig sind.
Mehrteiligen Upload ausführen
Mit einer Anfrage für einen mehrteiligen Upload 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 Verbindungsausfall noch einmal komplett hochzuladen.
Verwenden Sie die Methode files.create
mit uploadType=multipart
, um einen mehrteiligen Upload durchzuführen.
Im Folgenden wird beschrieben, wie ein mehrteiliger Upload durchgeführt wird:
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 Anfragetext. Formatieren Sie den Text gemäß dem Inhaltstyp „multipart/related“ (RFC 2387), der zwei Teile enthält:
- Metadaten: Die Metadaten müssen zuerst kommen und einen
Content-Type
-Header haben, der aufapplication/json;
charset=UTF-8
gesetzt ist. Fügen Sie die Metadaten der Datei im JSON-Format hinzu. - Medien. Die Medien müssen an zweiter Stelle stehen und eine
Content-Type
-Überschrift mit beliebigem MIME-Typ haben. Fügen Sie die Daten der Datei dem Medienteil hinzu.
Kennzeichnen 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 zuerst kommen und einen
Fügen Sie die folgenden HTTP-Header der obersten Ebene hinzu:
Content-Type
. Setzen Sie den Wert aufmultipart/related
und fügen Sie den Grenzstring ein, den Sie zum Identifizieren der verschiedenen Teile der Anfrage verwenden. 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 erstellen oder aktualisieren möchten, ohne die zugehörigen Daten hochzuladen, senden Sie eine POST
- oder PATCH
-Anfrage an den Standardressourcenendpunkt:
https://www.googleapis.com/drive/v3/files
Ist die Anfrage erfolgreich, gibt der Server den Statuscode HTTP 200 OK
zusammen mit den Metadaten der Datei zurück.
Beim Erstellen von Dateien muss im Feld name
der Datei eine Dateiendung angegeben werden. Wenn Sie beispielsweise eine JPEG-Fotodatei erstellen, können Sie in den Metadaten etwas wie "name": "photo.jpg"
angeben. Bei nachfolgenden Aufrufen von files.get
wird die schreibgeschützte Eigenschaft fileExtension
zurückgegeben, die die ursprünglich im Feld name
angegebene Erweiterung enthält.
Fortsetzbaren Upload ausfü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 vorn beginnen müssen, können Sie mit fortsetzbaren Uploads auch die Bandbreitennutzung bei einem Netzwerkausfall reduzieren.
Fortsetzbare Uploads sind nützlich, wenn die Dateigrößen stark variieren oder wenn für Anfragen ein festes Zeitlimit gilt (z. B. Hintergrundaufgaben von mobilen Betriebssystemen und bestimmte App Engine-Anfragen). Sie können fortsetzbare Uploads auch verwenden, wenn Sie eine Upload-Fortschrittsanzeige anzeigen möchten.
Ein fortsetzbarer Upload umfasst mehrere allgemeine Schritte:
- Sende die erste Anfrage und hole den URI der fortsetzbaren Sitzung ab.
- Laden Sie die Daten hoch und beobachten 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 Anfrage zum Starten erfolgreich war, 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 Sie Metadaten für die Datei haben, fügen Sie diese dem Anfragetext im JSON-Format hinzu. Ansonsten lassen Sie den Anfragetext leer.
Fügen Sie die folgenden 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.
X-Upload-Content-Length
. Optional. Legen Sie als Wert die Anzahl von Byte für die Dateidaten fest, die in nachfolgenden Anfragen übertragen werden.Content-Type
. Dies ist erforderlich, wenn Sie Metadaten für die Datei haben. Legen Sieapplication/json;
charset=UTF-8
fest.Content-Length
. Erforderlich, sofern Sie nicht die aufgeteilte Transferverschlüsselung verwenden. Legen Sie als Wert die Anzahl von Byte fest, die im Text dieser ersten Anfrage vorhanden sind.
Senden Sie die Anfrage. Wenn die Anfrage zum Starten der Sitzung erfolgreich war, enthält die Antwort den Statuscode
200 OK HTTP
. Außerdem 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 Upload der Inhalte fort.
Inhalte hochladen
Es gibt zwei Möglichkeiten, eine Datei mit einer fortsetzbaren Sitzung hochzuladen:
- Inhalte in einer einzigen Anfrage hochladen: Verwenden Sie diesen Ansatz, wenn die Datei in einer Anfrage hochgeladen werden kann, wenn für einzelne Anfragen kein festes Zeitlimit vorgegeben ist oder wenn Sie keine Fortschrittsanzeige für den Upload anzeigen müssen. Dieser Ansatz ist am besten geeignet, da er weniger Anfragen erfordert und zu einer besseren Leistung führt.
In mehreren Blöcken hochladen: Verwenden Sie diesen Ansatz, wenn Sie die Datenmenge reduzieren müssen, die bei einer einzelnen Anfrage übertragen wird. Unter Umständen müssen Sie die übertragenen Daten reduzieren, wenn für einzelne Anfragen eine feste Zeitbegrenzung vorliegt (z. B. für bestimmte Arten von App Engine-Anfragen). Dieser Ansatz ist auch nützlich, wenn Sie eine benutzerdefinierte Anzeige für den Uploadfortschritt bereitstellen müssen.
HTTP – einzelne Anfrage
- 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 HTTP-Header „Content-Length“ hinzu, der auf die Anzahl der Byte in der Datei gesetzt 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 Teile in Vielfachen von 256 KB (256 x 1024 Byte), mit Ausnahme des letzten Teils, der den Upload vervollständigt. Halten Sie die Blockgröße so groß wie möglich, damit der Upload effizient ist.
Fügen Sie die folgenden 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. Beispielsweise zeigtContent-Range: bytes 0-524287/2000000
an, dass die ersten 524.288 Byte (256 x 1024 x 2) in einer 2.000.000 Byte großen Datei hochgeladen werden.
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 verbleibenden Teil der Datei. Verwenden Sie den Header
Range
in der Antwort, um festzulegen, wo der nächste Teil beginnt. Gehen Sie nicht davon aus, dass der Server alle in der vorherigen Anfrage gesendeten Bytes erhalten hat.
Wenn der gesamte Dateiupload abgeschlossen ist, erhalten Sie eine 200 OK
- oder 201 Created
-Antwort zusammen mit allen Metadaten, die mit der Ressource verknüpft sind.
Unterbrochenen Upload fortsetzen
Wird die Uploadanfrage vor dem Erhalten einer Antwort beendet oder erhalten Sie die Antwort 503
Service Unavailable
, 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, der anzeigt, dass die derzeitige Position in der Datei unbekannt ist. Setzen Sie beispielsweiseContent-Range
auf*/2000000
, wenn die Dateigröße insgesamt 2.000.000 Byte ist. Sollte die Gesamtgröße der Datei nicht bekannt sein, legen Sie fürContent-Range
den Wert*/*
fest.Senden Sie die Anfrage.
Antwort verarbeiten:
- Eine
200 OK
- oder201 Created
-Antwort gibt an, dass der Upload abgeschlossen wurde und keine weiteren Maßnahmen erforderlich sind. - Die
308 Resume Incomplete
-Antwort gibt an, dass Sie das Hochladen der Datei fortsetzen müssen. - Eine
404 Not Found
-Antwort gibt an, dass die Uploadsitzung abgelaufen ist und der Upload von vorn begonnen werden muss.
- Eine
Wenn Sie eine
308 Resume Incomplete
-Antwort erhalten haben, verarbeiten Sie denRange
-Header der Antwort, um zu ermitteln, welche Bytes der Server empfangen hat. Wenn die Antwort keinenRange
-Header hat, wurden keine Bytes empfangen. Der HeaderRange
mit einem Wert vonbytes=0-42
gibt beispielsweise an, dass die ersten 43 Byte der Datei empfangen wurden und dass der nächste zum Hochladen vorgesehene Teil mit Byte 44 beginnt.Fahren Sie nun, da Sie wissen, wo Sie den Upload fortsetzen müssen, mit dem Hochladen der Datei fort. Beginnen Sie dabei mit dem nächsten Byte. Fügen Sie einen
Content-Range
-Header hinzu, der angibt, welcher Teil der Datei gesendet wird.Content-Range: bytes 43-1999999
gibt beispielsweise an, dass Sie die Bytes 44 bis 2.000.000 senden.
Fehler beim Hochladen von Medien beheben
Beachten Sie beim Hochladen von Medien die folgenden Best Practices zur Fehlerbehandlung:
- Bei
5xx
-Fehlern können Sie Uploads, die aufgrund von Verbindungsunterbrechungen fehlgeschlagen sind, fortsetzen oder noch einmal versuchen. Weitere Informationen zur Behandlung von5xx
-Fehlern finden Sie unter 500-, 502-, 503- und 504-Fehler. - Wiederholen Sie den Upload bei
403 rate limit
-Fehlern. Weitere Informationen zum Umgang mit403 rate limit
-Fehlern findest du unter 403-Fehler:rateLimitExceeded
. - Starten Sie den Upload bei
4xx
-Fehlern (einschließlich403
) während eines fortsetzbaren Uploads neu. Diese Fehler weisen darauf hin, dass die Uploadsitzung abgelaufen ist und neu gestartet werden muss. Fordere dazu einen neuen Sitzungs-URI an. Uploadsitzungen laufen ebenfalls nach einer Woche Inaktivität ab.
Importtypen für Google Docs
Wenn Sie eine Datei in Drive erstellen, können Sie sie in einen Google Workspace-Dateityp wie Google Docs oder Google Tabellen konvertieren. Vielleicht möchten Sie beispielsweise ein Dokument aus Ihrer bevorzugten Textverarbeitungssoftware in Google Docs umwandeln, um die Funktionen von Google Docs zu nutzen.
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 beschrieben, wie Sie eine CSV-Datei in eine Google Workspace-Tabelle konvertieren:
Java
Python
Node.js
PHP
.NET
Ob eine Conversion verfügbar ist, sehen Sie im importFormats
-Array der Ressource about
, bevor Sie die Datei erstellen.
Unterstützte Conversions sind in diesem Array dynamisch verfügbar. Gängige Importformate:
Von | An |
---|---|
Microsoft Word, OpenDocument-Text, HTML, RTF, Nur-Text | Google Docs |
Microsoft Excel, OpenDocument-Tabelle, CSV, TSV, Nur-Text | Google Sheets |
Microsoft PowerPoint, OpenDocument-Präsentation | Google Präsentationen |
JPEG, PNG, GIF, BMP, PDF | Google Docs (das Bild wird in ein Dokument eingebettet) |
Nur Text (spezielle MIME-Art), JSON | Google Apps Script |
Wenn Sie Medien während einer update
-Anfrage in eine Docs-, Sheets- oder Präsentationen-Datei hochladen und konvertieren, wird der gesamte Inhalt des Dokuments ersetzt.
Wenn Sie ein Bild in Google Drive in ein Docs-Dokument konvertieren, wird die optische Zeichenerkennung (Optical Character Recognition, OCR) verwendet, um das Bild in Text umzuwandeln. 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.
Vorab generierte ID zum Hochladen von Dateien verwenden
Mit der Drive API können Sie eine Liste der vorab generierten Datei-IDs abrufen, die zum Hochladen und Erstellen von Ressourcen verwendet werden. Diese vorab generierten IDs können für Upload- und Dateierstellungsanfragen verwendet werden. Legen Sie das Feld id
in den Dateimetadaten fest.
Wenn Sie vorab generierte IDs erstellen möchten, rufen Sie files.generateIds
mit der Anzahl der zu erstellenden IDs auf.
Wenn ein unbestimmter Serverfehler oder eine Zeitüberschreitung auftritt, können Sie Uploads mit vorab generierten IDs noch einmal versuchen. Wenn die Datei erfolgreich erstellt wurde, wird bei nachfolgenden Versuchen ein HTTP 409
-Fehler zurückgegeben und es werden keine doppelten Dateien erstellt.
Indexierbaren Text für unbekannte Dateitypen definieren
Nutzer können über die Drive-Benutzeroberfläche nach Dokumentinhalten suchen. Sie können auch files.list
und das Feld fullText
verwenden, um nach Inhalten in Ihrer App 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. Dazu gehören Textdokumente, PDFs, Bilder mit Text und andere gängige Dateitypen. Wenn Ihre App andere Dateitypen speichert (z. B. Zeichnungen, Videos und Verknüpfungen), können Sie die Auffindbarkeit verbessern, indem Sie im Feld contentHints.indexableText
der Datei indexierbaren Text angeben.
Weitere Informationen zu indexierbarem Text finden Sie unter Dateimetadaten verwalten.