Diese Seite wurde von der Cloud Translation API übersetzt.

Fortsetzbare Uploads

Mit dem Protokoll für fortsetzbare Uploads für Google APIs können Sie Videos zuverlässiger hochladen. Mit diesem Protokoll können Sie einen Uploadvorgang nach einer Netzwerkunterbrechung oder einem anderen Übertragungsfehler fortsetzen. So sparen Sie bei Netzwerkausfällen Zeit und Bandbreite.

Die Verwendung von fortsetzbaren Uploads ist in folgenden Fällen besonders nützlich:

Sie übertragen große Dateien.
Die Wahrscheinlichkeit einer Netzwerkunterbrechung ist hoch.
Die Uploads stammen von einem Gerät mit geringer Bandbreite oder instabiler Internetverbindung, z. B. einem Mobilgerät.

In diesem Leitfaden wird die Abfolge der HTTP-Anfragen beschrieben, die eine Anwendung für den Upload von Videos mit einem fortsetzbaren Uploadprozess sendet. Dieser Leitfaden richtet sich in erster Linie an Entwickler, die die Google API-Clientbibliotheken nicht verwenden können. Einige davon bieten native Unterstützung für fortsetzbare Uploads. Im Leitfaden YouTube Data API – Video hochladen wird beschrieben, wie du mit der Google APIs-Clientbibliothek für Python ein Video mit einem fortsetzbaren Uploadprozess hochlädst.

Hinweis:Sie können sich auch die Reihe von Anfragen für den fortsetzbaren Upload oder einen anderen API-Vorgang ansehen, indem Sie eine der Google API-Clientbibliotheken mit aktivierter HTTPS-Protokollierung verwenden. Wenn Sie beispielsweise die HTTP-Spuren für Python aktivieren möchten, verwenden Sie die Bibliothek httplib2:

httplib2.debuglevel = 4

Schritt 1: Fortsetzbare Sitzung starten

Wenn du einen fortsetzbaren Videoupload starten möchtest, sende eine POST-Anfrage an die folgende URL. Legen Sie in der URL den Parameterwert part auf den für Ihre Anfrage geeigneten Wert fest. Der Parameterwert gibt die Teile an, die die von Ihnen festgelegten Properties enthalten, und auch die Teile, die in der API-Antwort enthalten sein sollen. Parameterwerte in der Anfrage-URL müssen URL-codiert sein.

https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=PARTS

Legen Sie den Anfragetext auf eine video-Ressource fest. Legen Sie auch die folgenden HTTP-Anfrage-Header fest:

Authorization: Das Autorisierungstoken für die Anfrage.
Content-Length: Die Anzahl der Byte, die im Text der Anfrage angegeben sind. Dieser Header ist nicht erforderlich, wenn du die aufgeteilte Transferverschlüsselung verwendest.
Content-Type – Legen Sie den Wert auf application/json; charset=UTF-8 fest.
X-Upload-Content-Length: Die Anzahl der Byte, die in nachfolgenden Anfragen hochgeladen werden. Legen Sie diesen Wert auf die Größe der hochgeladenen Datei fest.
x-upload-content-type – der MIME-Typ der hochgeladenen Datei. Sie können Dateien mit einem beliebigen Video-MIME-Typ (video/*) oder einem MIME-Typ von application/octet-stream hochladen.

Im folgenden Beispiel wird gezeigt, wie eine fortsetzbare Sitzung für den Upload eines Videos gestartet wird. Dabei werden Eigenschaften in den Teilen snippet und status der video-Ressource festgelegt und abgerufen. Außerdem werden Eigenschaften im Teil contentdetails der Ressource abgerufen.

post /upload/youtube/v3/videos?uploadType=resumable&part=parts http/1.1
host: www.googleapis.com
authorization: bearer auth_token
content-length: content_length
content-type: application/json; charset=utf-8
x-upload-content-length: x_upload_content_length
X-Upload-Content-Type: X_UPLOAD_CONTENT_TYPE

video resource

Das folgende Beispiel zeigt eine POST-Anfrage, in der alle diese Werte mit Ausnahme des Authentifizierungstokens ausgefüllt sind. Der Wert categoryId im Beispiel entspricht einer Videokategorie. Die Liste der unterstützten Kategorien kann mit der videoCategories.list-Methode der API abgerufen werden.

POST /upload/youtube/v3/videos?uploadType=resumable&part=snippet,status,contentDetails HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer AUTH_TOKEN
Content-Length: 278
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Length: 3000000
X-Upload-Content-Type: video/*

{
  "snippet": {
    "title": "My video title",
    "description": "This is a description of my video",
    "tags": ["cool", "video", "more keywords"],
    "categoryId": 22
  },
  "status": {
    "privacyStatus": "public",
    "embeddable": True,
    "license": "youtube"
  }
}

Schritt 2: URI der fortsetzbaren Sitzung speichern

Wenn die Anfrage erfolgreich ist, antwortet der API-Server mit dem HTTP-Statuscode 200 (OK) und der Antwort enthält einen Location-HTTP-Header, der den URI für die fortsetzbare Sitzung angibt. Über diesen URI laden Sie Ihre Videodatei hoch.

Das folgende Beispiel zeigt eine Beispiel-API-Antwort auf die Anfrage in Schritt 1:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&upload_id=xa298sd_f&part=snippet,status,contentDetails
Content-Length: 0

Schritt 3: Videodatei hochladen

Nachdem du den Sitzungs-URI aus der API-Antwort extrahiert hast, musst du den Inhalt der Videodatei an diesen Speicherort hochladen. Der Textkörper der Anfrage ist der Binärdateiinhalt des hochgeladenen Videos. Das Beispiel unten zeigt das Format der Anfrage.

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: CONTENT_LENGTH
Content-Type: CONTENT_TYPE

BINARY_FILE_DATA

In der Anfrage werden die folgenden HTTP-Anfrageheader festgelegt:

Authorization: Das Autorisierungstoken für die Anfrage.
Content-Length: Die Größe der hochgeladenen Datei. Dieser Wert sollte mit dem Wert des X-Upload-Content-Length-HTTP-Anfrageheaders in Schritt 1 übereinstimmen.
Content-Type: Der MIME-Typ der hochgeladenen Datei. Dieser Wert sollte mit dem Wert des X-Upload-Content-Type-HTTP-Anfrageheaders in Schritt 1 übereinstimmen.

Schritt 4: Upload abschließen

Ihre Anfrage führt zu einem der folgenden Szenarien:

Der Upload war erfolgreich.

Der API-Server antwortet mit dem HTTP-Antwortcode 201 (Created). Der Textkörper der Antwort ist die von Ihnen erstellte video-Ressource.
Der Upload war nicht erfolgreich, kann aber fortgesetzt werden.

In den folgenden Fällen sollten Sie einen Upload fortsetzen können:
- Ihre Anfrage wird unterbrochen, weil die Verbindung zwischen Ihrer Anwendung und dem API-Server unterbrochen wurde. In diesem Fall erhältst du keine API-Antwort.
- In der API-Antwort wird einer der folgenden 5xx-Antwortcodes angegeben. Ihr Code sollte eine exponentielle Backoff-Strategie verwenden, wenn Uploads nach Erhalt eines dieser Antwortcodes fortgesetzt werden.
  - 500 – Internal Server Error
  - 502 – Bad Gateway
  - 503 – Service Unavailable
  - 504 – Gateway Timeout
Wenn Sie einen Upload fortsetzen möchten, folgen Sie der Anleitung unten zum Prüfen des Uploadstatus und Fortsetzen eines Uploads. Jeder URI einer fortsetzbaren Sitzung hat eine begrenzte Lebensdauer und läuft irgendwann ab. Aus diesem Grund empfehlen wir, einen fortsetzbaren Upload zu starten, sobald Sie den Sitzungs-URI erhalten haben, und einen unterbrochenen Upload kurz nach der Unterbrechung fortzusetzen.
Der Upload ist dauerhaft fehlgeschlagen.

Bei einem fehlgeschlagenen Upload enthält die Antwort eine Fehlerantwort, die die Ursache des Fehlers erklärt. Bei einem Upload, der dauerhaft fehlschlägt, enthält die API-Antwort einen anderen 4xx- oder 5xx-Antwortcode als die oben aufgeführten.

Wenn Sie eine Anfrage mit einem abgelaufenen Sitzungs-URI senden, gibt der Server einen 404-HTTP-Antwortcode (Not Found) zurück. In diesem Fall müssen Sie einen neuen fortsetzbaren Upload starten, einen neuen Sitzungs-URI abrufen und den Upload unter Verwendung des neuen URIs von vorn beginnen.

Schritt 4.1: Status eines Uploads prüfen

Wenn Sie den Status eines unterbrochenen, fortsetzbaren Uploads prüfen möchten, senden Sie eine leere PUT-Anfrage an die Upload-URL, die Sie in Schritt 2 abgerufen und auch in Schritt 3 verwendet haben. Legen Sie in Ihrer Anfrage den Headerwert Content-Range auf bytes */CONTENT_LENGTH fest. Dabei ist CONTENT_LENGTH die Größe der Datei, die Sie hochladen.

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: 0
Content-Range: bytes */CONTENT_LENGTH

Schritt 4.2: API-Antwort verarbeiten

Wenn der Upload bereits abgeschlossen ist, unabhängig davon, ob er erfolgreich war oder fehlgeschlagen ist, gibt die API dieselbe Antwort zurück, die sie beim ursprünglichen Abschluss des Uploads gesendet hat.

Wenn der Upload jedoch unterbrochen wurde oder noch läuft, enthält die API-Antwort den HTTP-Antwortcode 308 (Resume Incomplete). In der Antwort gibt der Header Range an, wie viele Byte der Datei bereits erfolgreich hochgeladen wurden.

Der Headerwert wird ab 0 indexiert. Ein Headerwert von 0-999999 gibt also an, dass die ersten 1,000,000 Byte der Datei hochgeladen wurden.
Wenn noch nichts hochgeladen wurde, enthält die API-Antwort keinen Range-Header.

Die folgende Beispielantwort zeigt das Format einer API-Antwort für einen fortsetzbaren Upload:

308 Resume Incomplete
Content-Length: 0
Range: bytes=0-999999

Wenn die API-Antwort auch den Retry-After-Header enthält, kannst du anhand des Werts dieses Headers ermitteln, wann der Upload fortgesetzt werden soll.

Schritt 4.3: Upload fortsetzen

Wenn Sie den Upload fortsetzen möchten, senden Sie eine weitere PUT-Anfrage an die in Schritt 2 erfasste Upload-URL. Legen Sie den Anfragetext auf den Binärcode für den Teil der Videodatei fest, der noch nicht hochgeladen wurde.

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: REMAINING_CONTENT_LENGTH
Content-Range: bytes FIRST_BYTE-LAST_BYTE/TOTAL_CONTENT_LENGTH

PARTIAL_BINARY_FILE_DATA

Sie müssen die folgenden HTTP-Anfrage-Header festlegen:

Authorization: Das Autorisierungstoken für die Anfrage.
Content-Length – Die Größe der Inhalte in Byte, die noch nicht hochgeladen wurden. Wenn Sie den Rest einer Datei hochladen, können Sie diesen Wert berechnen, indem Sie den Wert FIRST_BYTE von TOTAL_CONTENT_LENGTH subtrahieren. Beide Werte werden im Header Content-Range verwendet.
Content-Range: Der Teil der Datei, den Sie hochladen. Der Header-Wert besteht aus drei Werten:
- FIRST_BYTE: Der numerische Index (nullbasiert) der Bytenummer, ab der der Upload fortgesetzt wird. Dieser Wert ist um eine Zahl höher als die zweite Zahl im Range-Header, die im vorherigen Schritt abgerufen wurde. Im vorherigen Beispiel lautete der Range-Headerwert 0-999999. Das erste Byte in einem anschließend fortgesetzten Upload wäre also 1000000.
- LAST_BYTE: Der numerische Index (nullbasiert) des letzten Bytes der hochgeladenen Binärdatei. Normalerweise ist dies das letzte Byte in der Datei. Wenn die Datei beispielsweise 3000000 Byte groß ist, hat das letzte Byte der Datei die Nummer 2999999.
- TOTAL_CONTENT_LENGTH: Die Gesamtgröße der Videodatei in Byte. Dieser Wert stimmt mit dem Content-Length-Header überein, der in der ursprünglichen Uploadanfrage angegeben wurde.
Hinweis:Sie können keinen nicht zusammenhängenden Block der Binärdatei hochladen. Wenn Sie versuchen, einen nicht zusammenhängenden Block hochzuladen, werden keine der verbleibenden binären Inhalte hochgeladen.

Daher muss das erste Byte, das bei einem fortgesetzten Upload hochgeladen wird, das nächste Byte nach dem letzten Byte sein, das bereits erfolgreich auf YouTube hochgeladen wurde. Weitere Informationen zum Range-Header finden Sie in Schritt 4.2.

Wenn also das letzte Byte im Range-Header 999999 ist, muss das erste Byte in der Anfrage zur Wiederaufnahme des Uploads das Byte 1000000 sein. (Beide Zahlen haben einen Index, der auf 0 basiert.) Wenn Sie versuchen, den Upload bei Byte 999999 oder niedriger fortzusetzen (überlappende Byte) oder bei Byte 1000001 oder höher (Byte überspringen), werden keine binären Inhalte hochgeladen.

Datei in Teilen hochladen

Anstatt zu versuchen, eine ganze Datei hochzuladen und den Upload bei einer Netzwerkunterbrechung fortzusetzen, kann Ihre Anwendung die Datei in mehrere Teile aufteilen und eine Reihe von Anfragen senden, um die Teile der Reihe nach hochzuladen. Dieser Ansatz ist selten erforderlich und wird eigentlich nicht empfohlen, da er zusätzliche Anfragen erfordert, was sich auf die Leistung auswirkt. Sie kann jedoch nützlich sein, wenn Sie in einem sehr instabilen Netzwerk eine Fortschrittsanzeige anzeigen möchten.

Die Anleitung zum Hochladen einer Datei in mehreren Teilen entspricht praktisch dem vierstufigen Verfahren, das weiter oben in diesem Leitfaden beschrieben wurde. Bei den Anfragen zum Starten des Uploads einer Datei (Schritt 3 oben) und zum Fortsetzen eines Uploads (Schritt 4.3 oben) werden die Headerwerte Content-Length und Content-Range jedoch unterschiedlich festgelegt, wenn eine Datei in Teilen hochgeladen wird.

Der Content-Length-Headerwert gibt die Größe des Chunks an, der mit der Anfrage gesendet wird. Beachten Sie die folgenden Einschränkungen bei der Größe von Segmenten:
- Die Blockgröße muss ein Vielfaches von 256 KB sein. Diese Einschränkung gilt nicht für den letzten Teil, da die Größe der gesamten Datei möglicherweise kein Vielfaches von 256 KB ist. Denken Sie daran, dass größere Chunks effizienter sind.
- Die Größe der Teile muss für jede Anfrage in der Uploadsequenz gleich sein, mit Ausnahme der letzten Anfrage, die die Größe des letzten Teils angibt.
Der Content-Range-Header gibt die Anzahl der Bytes in der Datei an, die über die Anfrage hochgeladen werden. Die Anleitung zum Festlegen der Überschrift Content-Range in Schritt 4.3 gilt auch für diesen Wert.

Ein Wert von bytes 0-524287/2000000 gibt beispielsweise an, dass mit der Anfrage die ersten 524.288 Byte (256 x 2048) in einer 2.000.000 Byte großen Datei gesendet werden.

Das folgende Beispiel zeigt das Format der ersten Anfrage einer Reihe von Anfragen, mit denen eine Datei mit 2.000.000 Byte in mehreren Teilen hochgeladen wird:

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: 524888
Content-Type: video/*
Content-Range: bytes 0-524287/2000000

{bytes 0-524287}

Wenn eine andere Anfrage als die letzte erfolgreich ist, antwortet der API-Server mit einer 308-Antwort (Resume Incomplete). Das Antwortformat entspricht dem oben in Schritt 4.2: API-Antwort verarbeiten beschriebenen Format.

Verwenden Sie den oberen Wert, der über den Range-Header in der API-Antwort zurückgegeben wird, um zu ermitteln, wo der nächste Teil beginnt. Senden Sie weiterhin PUT-Anfragen, wie in Schritt 4.3: Upload fortsetzen beschrieben, um weitere Dateiteile hochzuladen, bis die gesamte Datei hochgeladen wurde.

Wenn die gesamte Datei hochgeladen wurde, antwortet der Server mit einem 201-HTTP-Antwortcode (Created) und gibt die angeforderten Teile der neu erstellten Videoressource zurück.

Wenn eine Anfrage unterbrochen wird oder Ihre Anwendung einen 5xx-Antwortcode erhält, folgen Sie der Anleitung unter Schritt 4, um den Upload abzuschließen. Anstatt den Rest der Datei hochzuladen, setzen Sie einfach das Hochladen der Teile ab dem Punkt fort, an dem Sie den Upload fortsetzen. Prüfen Sie den Uploadstatus, um festzustellen, wo der Dateiupload fortgesetzt werden soll. Gehen Sie nicht davon aus, dass der Server alle oder keine der in der vorherigen Anfrage gesendeten Bytes erhalten hat.

Hinweis:Sie können auch den Status eines aktiven Uploads zwischen hochgeladenen Teilen anfordern. Der Upload muss nicht unterbrochen worden sein, damit Sie den Status abrufen können.