Diese Seite wurde von der Cloud Translation API übersetzt.

Fortsetzbare Uploads

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

Fortsetzbare Uploads sind in folgenden Fällen besonders hilfreich:

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

In diesem Leitfaden wird die Reihenfolge der HTTP-Anfragen erläutert, die von einer Anwendung zum Hochladen von Videos mithilfe eines fortsetzbaren Uploads gestellt werden. Dieser Leitfaden richtet sich in erster Linie an Entwickler, die die Google API-Clientbibliotheken nicht verwenden können. Einige bieten native Unterstützung für fortsetzbare Uploads. Im Leitfaden YouTube Data API – Video hochladen wird erläutert, wie Sie mit der Google APIs-Clientbibliothek für Python ein Video mithilfe eines fortsetzbaren Uploads hochladen.

Hinweis: Sie können auch die Reihe der Anfragen für den fortsetzbaren Upload oder für andere API-Vorgänge sehen, indem Sie eine der Google API-Clientbibliotheken mit aktiviertem HTTPS-Logging verwenden. Wenn Sie beispielsweise den HTTP-Trace für Python aktivieren möchten, verwenden Sie die Bibliothek httplib2:

httplib2.debuglevel = 4

Schritt 1: Fortsetzbare Sitzung starten

Senden Sie zum Starten eines fortsetzbaren Videouploads eine POST-Anfrage an die folgende URL. Legen Sie in der URL den Wert des Parameters part auf den entsprechenden Wert für Ihre Anfrage fest. Denken Sie daran, dass der Parameterwert die Teile definiert, die von Ihnen festgelegte Eigenschaften enthalten, und auch die Teile, die die API-Antwort enthalten soll. 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 Hauptteil der Anfrage auf eine video-Ressource fest. Legen Sie außerdem die folgenden HTTP-Anfrageheader fest:

Authorization: Das Autorisierungstoken für die Anfrage.
Content-Length: Anzahl der Byte im Text der Anfrage. Sie müssen diesen Header nicht angeben, wenn Sie die aufgeteilte Transferverschlüsselung verwenden.
Content-Type: Legen Sie den Wert auf application/json; charset=UTF-8 fest.
X-Upload-Content-Length: Die Anzahl der Byte, die in den nachfolgenden Anfragen hochgeladen werden. Legen Sie diesen Wert auf die Größe der Datei fest, die Sie hochladen.
x-upload-content-type: Der MIME-Typ der Datei, die Sie hochladen. Du kannst Dateien mit einem beliebigen Video-MIME-Typ (video/*) oder dem MIME-Typ application/octet-stream hochladen.

Das folgende Beispiel zeigt, wie Sie eine fortsetzbare Sitzung zum Hochladen eines Videos initiieren. Die Anfrage legt die Attribute in den snippet- und status-Teilen der video-Ressource fest und ruft sie ab. Außerdem werden Attribute im contentdetails-Teil 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, bei der alle diese Werte mit Ausnahme des Authentifizierungstokens ausgefüllt werden. Der Wert categoryId im Beispiel entspricht einer Videokategorie. Die Liste der unterstützten Kategorien kann mit der Methode videoCategories.list 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 Ihre Anfrage erfolgreich ist, antwortet der API-Server mit dem HTTP-Statuscode 200 (OK). Die Antwort enthält einen HTTP-Header Location, der den URI für die fortsetzbare Sitzung angibt. Das ist der URI zum Hochladen der Videodatei.

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 Sie den Sitzungs-URI aus der API-Antwort extrahiert haben, müssen Sie den tatsächlichen Inhalt der Videodatei an diesen Speicherort hochladen. Der Text der Anfrage ist der Inhalt der Binärdatei für das Video, das Sie hochladen. Das folgende Beispiel 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

Die Anfrage legt die folgenden HTTP-Anfrageheader fest:

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

Schritt 4: Uploadvorgang abschließen

Ihre Anfrage führt zu einem der folgenden Szenarien:

Der Upload wurde ausgeführt.

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

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

Bei einem fehlgeschlagenen Upload enthält die Antwort eine Fehlerantwort, die Aufschluss über die Fehlerursache gibt. Bei einem Upload, der dauerhaft fehlschlägt, hat die API-Antwort den Antwortcode 4xx oder den Antwortcode 5xx.

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 von vorn mit dem neuen URI starten.

Schritt 4.1: Uploadstatus prüfen

Senden Sie zum Prüfen des Status eines unterbrochenen fortsetzbaren Uploads eine leere PUT-Anfrage an die in Schritt 2 abgerufene und in Schritt 3 verwendete Upload-URL. Legen Sie in der Anfrage den Headerwert Content-Range auf bytes */CONTENT_LENGTH fest, wobei CONTENT_LENGTH die Größe der hochzuladenden Datei ist.

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, gibt die API unabhängig davon, ob der Upload erfolgreich war oder nicht, eine Antwort zurück, die beim ursprünglichen Upload gesendet wurde.

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 ist von 0 indexiert. Daher zeigt der Headerwert 0-999999 an, dass die ersten 1,000,000 Byte der Datei hochgeladen wurden.
Wenn noch nichts hochgeladen wurde, enthält die API-Antwort den Header Range nicht.

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 Header Retry-After enthält, können Sie anhand des Werts dieses Headers ermitteln, wann der Upload fortgesetzt werden soll.

Schritt 4.3: Upload fortsetzen

Senden Sie eine weitere PUT-Anfrage an die in Schritt 2 erfasste Upload-URL, um den Upload fortzusetzen. Setze den Anfragetext auf den binären Code für den Teil der Videodatei, 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-Anfrageheader festlegen:

Authorization: Das Autorisierungstoken für die Anfrage.
Content-Length: Die Größe des Inhalts in Byte, der noch nicht hochgeladen wurde. Wenn Sie den Rest einer Datei hochladen, können Sie diesen Wert berechnen, indem Sie den FIRST_BYTE-Wert vom TOTAL_CONTENT_LENGTH-Wert abziehen. Beide Werte werden im Content-Range-Header verwendet.
Content-Range: Der Teil der Datei, den Sie hochladen. Der Headerwert besteht aus drei Werten:
- FIRST_BYTE: Der 0-basierte numerische Index der Bytenummer, von der aus der Upload fortgesetzt wird. Dieser Wert ist eine Zahl höher als die zweite Zahl im Range-Header, die im vorherigen Schritt abgerufen wurde. Im vorherigen Beispiel betrug der Range-Headerwert 0-999999. Das erste Byte in einem nachfolgenden fortgesetzten Upload wäre daher 1000000.
- LAST_BYTE: der 0-basierte numerische Index des letzten Byte der Binärdatei, die Sie hochladen. In der Regel ist dies das letzte Byte in der Datei. Wenn die Dateigröße beispielsweise 3000000 Byte beträgt, hat das letzte Byte in der Datei den Wert 2999999.
- TOTAL_CONTENT_LENGTH: Die Gesamtgröße der Videodatei in Byte. Dieser Wert entspricht dem Header Content-Length, der in der ursprünglichen Uploadanfrage angegeben ist.
Hinweis: Sie können einen kontinuierlichen Block der Binärdatei nicht hochladen. Wenn Sie versuchen, einen nicht zusammenhängenden Block hochzuladen, wird keiner der verbleibenden binären Inhalte hochgeladen.

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

Wenn also das letzte Byte im Range-Header 999999 ist, muss das erste Byte in der Anfrage zum Fortsetzen des Uploads Byte 1000000 sein. (Beide Zahlen verwenden einen 0-basierten Index.) Wenn Sie versuchen, den Upload von Byte 999999 oder niedriger (überlappende Byte) oder Byte 1000001 oder höher (überspringende Byte) fortzusetzen, wird keiner der binären Inhalte hochgeladen.

Datei in Teilen hochladen

Anstatt zu versuchen, bei einer Netzwerkunterbrechung eine ganze Datei hochzuladen und den Upload fortzusetzen, kann Ihre Anwendung die Datei in Blöcke aufteilen und eine Reihe von Anfragen senden, um die Blöcke nacheinander hochzuladen. Dieser Ansatz ist selten erforderlich und wird auch tatsächlich nicht empfohlen, da er zusätzliche Anfragen mit Auswirkungen auf die Leistung erfordert. Es kann jedoch sinnvoll sein, eine Fortschrittsanzeige in einem sehr instabilen Netzwerk anzuzeigen.

Die Schritte zum Hochladen einer Datei in mehreren Blöcken sind nahezu identisch mit den vier Schritten, die weiter oben in diesem Leitfaden erläutert wurden. Durch die Anforderungen zum Starten des Hochladens einer Datei (Schritt 3 oben) und 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 Headerwert Content-Length gibt die Größe des Blocks an, den die Anfrage sendet. Beachten Sie die folgenden Einschränkungen für Chunk-Größen:
- Die Chunk-Größ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 ein Vielfaches von 256 KB sein darf. Denke daran, dass größere Blöcke effizienter sind.
- Die Chunk-Größe muss für jede Anfrage in der Uploadsequenz mit Ausnahme der letzten Anfrage, die die Größe des endgültigen Teils angibt, dieselbe sein.
Der Header Content-Range gibt die Byte in der Datei an, die von der Anfrage hochgeladen wird. Wenn Sie diesen Wert festlegen, gelten die Anleitungen zum Festlegen des Headers Content-Range in Schritt 4.3.

Der Wert bytes 0-524287/2000000 gibt beispielsweise an, dass die Anfrage die ersten 524.288 Byte (256 x 2048) in einer 2.000.000 Byte großen Datei sendet.

Das folgende Beispiel zeigt das Format der ersten Anfragereihe, mit der eine 2.000.000 Byte große Datei in 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 Anfrage erfolgreich ist, antwortet der API-Server mit der Antwort 308 (Resume Incomplete). Das Antwortformat ist dasselbe wie unter Schritt 4.2: API-Antwort verarbeiten beschrieben.

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

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

Wenn eine Anfrage unterbrochen wird oder Ihre Anwendung einen 5xx-Antwortcode erhält, folgen Sie der Anleitung in Schritt 4, um den Upload abzuschließen. Anstatt jedoch den Rest der Datei hochzuladen, können Sie einfach weiterhin Teile von dem Punkt aus hochladen, an dem Sie den Upload fortsetzen. Prüfen Sie anhand des Uploadstatus, wo der Dateiupload fortgesetzt werden kann. Gehen Sie nicht davon aus, dass der Server alle (oder keine) Byte erhalten hat, die in der vorherigen Anfrage gesendet wurden.

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