Paket erstellen

Uploadoptionen

Mit der Android Over The Air API kannst du Paketdaten hochladen, um eine neue Paketressource zu erstellen. Dies sind OTA-Pakete, die mit einer oder mehreren Konfigurationen verknüpft werden können, um das Update bereitzustellen auf Geräte übertragen werden.

Wir stellen ein Binärprogramm für Linux und Windows zur Verfügung, um das Hochladen von fortsetzbaren Paketen zu vereinfachen. kostenlos nutzbar sind, anstatt die unten beschriebenen Protokolle zu implementieren. Wenn Sie eine tiefer gehende -Integration verwenden, verwenden Sie bitte eines der unten beschriebenen Protokolle.

Linux

Lade den Upload-Client für Android Over The Air API Version 1 für Linux herunter.

Windows

Lade den Android Over The Air API-Uploader-Client Version 1 für Windows herunter.

Damit Sie sie verwenden können, müssen Sie zuerst ein Dienstkonto erstellen und eine JSON-Schlüsseldatei für dieses Konto abrufen. Weitere Informationen
Sobald Sie die Binärdatei und die Schlüsseldatei haben, können Sie sie mit Befehlszeilenoptionen ausführen, die Schlüsseldatei, die Bereitstellung und das Paket, das Sie hochladen. Bitte --help verwenden um alle Optionen zu sehen.

Uploadprotokolle

Uploadanfragen können folgendermaßen gestellt werden. Geben Sie die Methode an, die Sie für den X-Goog-Upload-Protocol-Anfrageheader verwenden.

  • Mehrteiliger Upload: X-Goog-Upload-Protocol: multipart. Zur schnellen Übertragung von kleinere Dateien und Metadaten; überträgt die Datei zusammen mit den Metadaten, die sie beschreiben, in einer einzigen Anfrage.
  • Fortsetzbarer Upload: X-Goog-Upload-Protocol: resumable. Für eine zuverlässige Übertragung, insbesondere bei größeren Dateien. Bei dieser Methode wird eine sitzungsinitiierende Anfrage verwendet, die optional Metadaten umfassen kann. Diese Strategie eignet sich für die meisten da es auch für kleinere Dateien funktioniert, allerdings nur für eine zusätzliche HTTP-Anfrage pro Upload.

Mehrteiliger Upload

Dies ist eine gute Wahl, wenn die gesendeten Daten klein sind. um den Upload wieder komplett zu starten, wenn die Verbindung fehlschlägt.

Wenn Sie den mehrteiligen Upload verwenden möchten, senden Sie eine POST-Anfrage an /upload/package URI und legen Sie X-Goog-Upload-Protocol auf multipart fest.

Zu den Top-Level-HTTP-Headern beim Stellen einer mehrteiligen Uploadanfrage gehören:

  • Content-Type Setzen Sie den Wert auf „multipart/related“ und fügen Sie den Begrenzungsstring ein, den Sie verwenden möchten. die Teile der Anfrage identifiziert werden.
  • Content-Length. Setzen Sie den Wert auf die Gesamtanzahl von Byte im Anfragetext.

Der Text der Anfrage ist als multipart/related-Inhalt formatiert geben Sie [RFC2387] ein und besteht aus genau zwei Teilen. Die Teile werden durch einen Grenzstring identifiziert und auf den finalen Grenzstring folgen zwei Bindestriche.

Für jeden Teil der mehrteiligen Anfrage ist als zusätzlicher Header Content-Type erforderlich:

  1. Metadatenteil:Muss als Erstes angegeben werden und Content-Type muss application/json sein.
  2. Medienteil: Muss als Zweites angegeben werden und Content-Type muss application/zip sein.

Beispiel: Mehrteiliger Upload

Das folgende Beispiel zeigt eine mehrteilige Uploadanfrage für die Android Over The Air API.

POST /upload/package HTTP/1.1
Host: androidovertheair.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=BOUNDARY
Content-Length: number_of_bytes_in_entire_request_body

--BOUNDARY
Content-Type: application/json; charset=UTF-8

{"deployment": "id", "package_title": "title" }
--BOUNDARY
Content-Type: application/zip; charset=UTF-8

Package ZIP
--BOUNDARY--

Wenn die Anfrage erfolgreich ist, gibt der Server den HTTP-Statuscode 200 OK zurück

HTTP/1.1 200

Das geht ganz einfach mit curl. und oauth2l. Unten sehen Sie eine Beispielanfrage. bei dem davon ausgegangen wird, dass Sie einen Dienstschlüssel verwenden (siehe unsere Autorisierung.

Beispiel für eine curl-Anfrage 
    JSON={"deployment": "id", "package_title": "title" }
    SERVICE_KEY_FILE=path to your service key json file
    curl \
    -H "$(./oauth2l header --json $SERVICE_KEY_FILE android_partner_over_the_air)" \
    -H "Host: androidovertheair.googleapis.com" \
    -H "X-Goog-Upload-Protocol: multipart" \
    -H "Content-Type: multipart/form-data" \
    -F "json=$JSON;type=application/json" \
    -F "data=@update.zip;type=application/zip" \
    androidovertheair.googleapis.com/upload/package

Fortsetzbarer Upload

Für einen zuverlässigeren Upload von Datendateien können Sie das Protokoll für fortsetzbare Uploads verwenden. Dieses Protokoll ermöglicht Sie können einen Uploadvorgang fortsetzen, nachdem ein Kommunikationsfehler den Datenfluss unterbrochen hat. Es ist besonders nützlich, wenn Sie große Dateien übertragen und die Wahrscheinlichkeit einer Netzwerkunterbrechung oder ein anderer Übertragungsfehler ist hoch, z. B. beim Hochladen von einer mobilen Client-App. Es die Bandbreitennutzung bei Netzwerkausfällen reduzieren, große Dateiuploads neu starten.

Das Protokoll für fortsetzbare Uploads verwendet mehrere Befehle:

  1. Starten Sie eine fortsetzbare Sitzung. Stellen Sie eine erste Anfrage an den Upload-URI, der den Parameter Metadaten und legt einen eindeutigen Speicherort für den fortsetzbaren Upload fest.
  2. Speichern Sie den URI der fortsetzbaren Sitzung. Speichern Sie den Sitzungs-URI, der im Antwort auf die ursprüngliche Anfrage; verwenden Sie ihn für die anderen Anfragen in dieser Sitzung.
  3. Laden Sie die Datei hoch. Senden Sie die gesamte ZIP-Datei oder einen Teil davon an den URI der fortsetzbaren Sitzung.

Außerdem müssen Anwendungen, die den fortsetzbaren Upload verwenden, Code zum Fortsetzen eines unterbrochenen Uploads enthalten. Wenn ein Upload unterbrochen wurde, herausfinden, wie viele Daten erfolgreich empfangen wurden, und dann den Upload ab diesem Punkt fortsetzen.

Hinweis : Ein Upload-URI läuft nach drei Tagen ab.

Schritt 1: Fortsetzbare Sitzung starten

Um einen fortsetzbaren Upload zu starten, senden Sie eine POST-Anfrage an /upload/package URI und legen Sie X-Goog-Upload-Protocol auf resumable fest.

Für diese initiierende Anfrage darf der body-Abschnitt nur die Metadaten enthalten. übertragen Sie die tatsächlichen der Datei, die Sie in nachfolgenden Anfragen hochladen möchten.

Verwenden Sie in der ersten Anfrage die folgenden HTTP-Header:

  • X-Goog-Upload-Header-Content-Type Dies ist der Inhaltstyp der Datei, die hochgeladen wird, und muss auf application/zip festgelegt werden.
  • X-Goog-Upload-Command Auf start festlegen
  • X-Goog-Upload-Header-Content-Length. Legen Sie als Wert die Anzahl von Byte für die Uploaddaten fest, die in den folgenden Anfragen übertragen werden sollen. Ist die Länge zu Beginn der Anfrage unbekannt, können Sie diesen Header weglassen.
  • Content-Type Dies ist der Inhaltstyp der Metadaten und muss auf application/json festgelegt werden.
  • Content-Length. Legen Sie als Wert die Anzahl von Byte fest, die im Text dieser ersten Anfrage bereitgestellt werden.
Beispiel: Anfrage zum Start einer fortsetzbaren Sitzung

Das folgende Beispiel zeigt, wie eine fortsetzbare Sitzung für die Android Over The Air API initiiert wird.

POST /upload/package HTTP/1.1
Host: android/over-the-air.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Goog-Upload-Command: start
X-Goog-Upload-Header-Content-Type: application/zip
X-Goog-Upload-Header-Content-Length: 2000000

{"deployment": "id", "package_title": "title" }

Im nächsten Abschnitt wird der Umgang mit der Antwort beschrieben.

Schritt 2: URI der fortsetzbaren Sitzung speichern

Wenn die Anfrage zum Starten der Sitzung erfolgreich war, antwortet der API-Server mit dem HTTP-Statuscode 200 OK. Außerdem stellt er einen X-Goog-Upload-URL-Header bereit, der den URI der fortsetzbaren Sitzung angibt. Der X-Goog-Upload-URL-Header, wie im folgenden Beispiel gezeigt, enthält einen upload_id-Abfrageparameter , der die eindeutige Upload-ID für diese Sitzung angibt. Die Antwort enthält auch ein X-Goog-Upload-Status. , der active lautet, wenn die Uploadanfrage gültig und akzeptiert wurde. Dieser Status kann final sein wenn der Upload abgelehnt wurde.

Beispiel: Antwort auf Anfrage zum Start einer fortsetzbaren Sitzung

Dies ist die Antwort auf die Anfrage in Schritt 1:

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-URL: androidovertheair.googleapis.com/?upload_id=xa298sd_sdlkj2
Content-Length: 0

Der Wert des X-Goog-Upload-URL-Headers, wie in der obigen Beispielantwort gezeigt, lautet Den Sitzungs-URI, den Sie als HTTP-Endpunkt für den eigentlichen Datei-Upload oder die Abfrage des Uploadstatus verwenden.

Kopieren und speichern Sie den Sitzungs-URI, damit Sie ihn für nachfolgende Anfragen verwenden können.

Schritt 3: Datei hochladen

Senden Sie zum Hochladen der Datei eine POST-Anfrage an den Upload-URI, den Sie im vorherigen Schritt. Das Format der Uploadanfrage lautet:

POST session_uri

Zu den HTTP-Headern, die bei Anfragen für fortsetzbare Dateiuploads verwendet werden, gehören:

  1. Content-Length Legen Sie hier die Anzahl der Bytes fest, die Sie in dieser Anfrage hochladen. Dies entspricht in der Regel der Größe der Uploaddatei.
  2. X-Goog-Upload-Command Legen Sie dafür upload und finalize fest.
  3. X-Goog-Upload-Offset Gibt den Offset an, mit dem Bytes geschrieben werden sollen. Beachten Sie, dass Clients müssen Bytes nacheinander hochladen.
Beispiel: Anfrage für fortsetzbaren Datei-Upload

Hier ist eine fortsetzbare Anfrage zum Hochladen der gesamten 2.000.000 Byte großen ZIP-Datei für das aktuelle Beispiel.

POST /?upload_id=xa298sd_sdlkj2 HTTP/1.1
Host: androidovertheair.googleapis.com
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0
Content-Length: 2000000
Content-Type: application/zip

bytes 0-1999999

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 Ok.

Wenn die Uploadanfrage unterbrochen wird oder Sie eine HTTP-503 Service Unavailable oder eine 5xx-Antwort vom Server zu senden, folgen Sie der Anleitung unter Unterbrochenen Upload fortsetzen.

Datei in Teilen hochladen

Bei fortsetzbaren Uploads können Sie eine Datei aufteilen und eine Reihe von Anfragen senden, um jeden Teil der Reihe nach hochzuladen. Dies ist nicht der bevorzugte Ansatz, da mit den zusätzlichen Anfragen Leistungskosten verbunden sind. in der Regel nicht erforderlich. Wir empfehlen, dass Clients alle verbleibenden Bytes der Nutzlast hochladen und Fügen Sie bei jedem upload-Befehl den Befehl finalize ein.

Möglicherweise müssen Sie die Aufteilung jedoch vornehmen, um die Menge der übertragenen Daten zu reduzieren. -Einzelanfrage. Außerdem können Sie damit beispielsweise den Upload-Fortschritt für ältere Browser anzeigen lassen. für die der Uploadfortschritt standardmäßig nicht unterstützt wird.

Unterbrochenen Upload fortsetzen

Wenn eine Uploadanfrage beendet wird, bevor Sie eine Antwort erhalten haben, oder wenn Sie eine HTTP 503 Service Unavailable-Antwort vom Server senden, müssen Sie den unterbrochenen Upload fortsetzen. Das geht so:

  1. Status abfragen. Fragen Sie den aktuellen Status des Uploads ab, indem Sie eine Anfrage an den Upload-URI senden. wobei X-Goog-Upload-Command auf query gesetzt ist.

    Hinweis :Es ist auch möglich, den Status zwischen Teilen anzufragen, und zwar nicht nur bei einer Unterbrechung des Uploads. Dies ist ist beispielsweise nützlich, wenn Sie Fortschrittsanzeigen für ältere Browser anzeigen möchten.

  2. Anzahl der hochgeladenen Byte abrufen. Verarbeiten Sie die Antwort der Statusabfrage. Der Server verwendet den X-Goog-Upload-Size-Received-Header in seiner Antwort, um anzugeben, wie viele Byte bisher empfangen wurden.
  3. Verbleibende Daten hochladen. Da Sie nun wissen, wo Sie die Anfrage fortsetzen müssen, senden Sie verbleibenden Daten oder aktuellen Block. Die verbleibenden Daten müssen in beiden Fällen als separater Block behandelt werden. müssen Sie den X-Goog-Upload-Offset-Header auf den richtigen Versatz setzen, wenn Sie den Upload fortsetzen.
Beispiel: Unterbrochenen Upload fortsetzen

1) Fordern Sie den Uploadstatus an.

POST /?upload_id=xa298sd_sdlkj2 HTTP/1.1
Host: androidovertheair.googleapis.com
X-Goog-Upload-Command: query

Wie bei allen Befehlen muss der Client den X-Goog-Upload-Status-Header in der HTTP-Antwort eines Abfragebefehls prüfen. Wenn der Header vorhanden ist und der Wert nicht active ist, wurde der Upload bereits beendet.

2) Extrahieren Sie die Anzahl von Byte, die bisher hochgeladen wurden, aus der Antwort.

In der Antwort des Servers wird mit dem Header X-Goog-Upload-Size-Received angegeben, dass die ersten 43 Bytes der Datei erhalten haben.

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 42

3) Setzen Sie den Upload von dem Punkt aus fort, an dem er unterbrochen wurde.

Die folgende Anfrage setzt den Upload fort, indem die verbleibenden Byte der Datei ab Byte 43 gesendet werden.

POST /?upload_id=xa298sd_sdlkj2 HTTP/1.1
Host: androidovertheair.googleapis.com
X-Goog-Upload-Command: upload, finalize
Content-Length: 1999957
X-Goog-Upload-Offset: 43

bytes 43-1999999

Best Practices

Beim Hochladen von Medien ist es hilfreich, einige Best Practices zur Fehlerbehandlung zu kennen.

  • Fortsetzen oder Wiederholen von Uploads, die aufgrund von Verbindungsunterbrechungen oder 5xx-Fehlern fehlgeschlagen sind, darunter:
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • Verwenden Sie einen exponentiellen Backoff, wenn beim Fortsetzen oder Wiederholen von Uploadanfragen ein Serverfehler des Typs 5xx zurückgegeben wird. Diese Fehler können auftreten, wenn ein Server überlastet ist. Mit exponentiellen Backoffs können solche Probleme in Zeiten mit sehr vielen Anfragen oder bei hohem Netzwerktraffic reduziert werden.
  • Andere Arten von Anfragen sollten nicht mit dem exponentiellen Backoff verarbeitet werden. Sie können jedoch eine Reihe von Anfragen wiederholen. Beschränken Sie dabei die Anzahl der Wiederholungen. Beispielsweise kann Ihr Code die Anzahl der Wiederholungsversuche auf maximal 10 beschränken, bevor ein Fehler gemeldet wird.
  • Wenn Sie bei fortsetzbaren Uploads 404 Not Found-Fehler beheben, starten Sie den gesamten Upload von vorn.

Exponentielle Backoffs

Exponentielle Backoffs bilden eine Standard-Fehlerbehandlungsstrategie für Netzwerkanwendungen, bei denen der Client eine fehlgeschlagene Anfrage über einen immer länger werdenden Zeitraum periodisch wiederholt. Wenn bei sehr vielen Anfragen oder bei hohem Netzwerktraffic der Server Fehler ausgibt, kann ein exponentieller Backoff eine hilfreiche Strategie zur Fehlerbehandlung sein. Dagegen ist ein exponentieller Backoff keine gute Strategie für die Handhabung von Fehlern, die nicht aufgrund des Netzwerkvolumens oder von Antwortzeiten auftreten, z. B. Fehler wegen ungültiger Autorisierungsdaten oder nicht gefundener Dateien.

Bei richtigem Einsatz erhöht der exponentielle Backoff die Effizienz der Bandbreitennutzung, verringert die Anzahl der Anfragen, die für den Erhalt einer erfolgreichen Antwort erforderlich sind, und maximiert den Durchsatz von Anfragen in Umgebungen mit Gleichzeitigkeit.

Der Ablauf für das Implementieren eines einfachen exponentiellen Backoffs sieht so aus:

  1. Stellen Sie eine Anfrage an die API.
  2. Sie erhalten eine HTTP 503-Antwort, die angibt, dass Sie die Anfrage wiederholen müssen.
  3. Warten Sie 1 Sekunde + random_number_milliseconds und wiederholen Sie die Anfrage.
  4. Sie erhalten eine HTTP 503-Antwort, die angibt, dass Sie die Anfrage wiederholen müssen.
  5. Warten Sie 2 Sekunden + random_number_milliseconds und wiederholen Sie die Anfrage.
  6. Sie erhalten eine HTTP 503-Antwort, die angibt, dass Sie die Anfrage wiederholen müssen.
  7. Warten Sie 4 Sekunden + random_number_milliseconds und wiederholen Sie die Anfrage.
  8. Sie erhalten eine HTTP 503-Antwort, die angibt, dass Sie die Anfrage wiederholen müssen.
  9. Warten Sie 8 Sekunden + random_number_milliseconds und wiederholen Sie die Anfrage.
  10. Sie erhalten eine HTTP 503-Antwort, die angibt, dass Sie die Anfrage wiederholen müssen.
  11. Warten Sie 16 Sekunden + random_number_milliseconds Millisekunden und wiederholen Sie die Anfrage.
  12. Beenden Sie den Vorgang. Melden oder protokollieren Sie einen Fehler.

Im oben beschriebenen Ablauf steht random_number_milliseconds für eine zufällige Anzahl von Millisekunden, deren Wert größer oder gleich 1.000 ist. Dies ist notwendig, da eine kleine zufällige Verzögerung dazu beiträgt, die Last gleichmäßiger zu verteilen und eine mögliche Überlastung des Servers zu vermeiden. Der Wert von random_number_milliseconds muss nach jeder Wartezeit neu definiert werden.

Hinweis: Die Wartezeit beträgt immer (2 ^ n) + random_number_milliseconds Millisekunden, wobei n eine gleichförmig ansteigende Ganzzahl ist, die anfänglich auf 0 gesetzt ist. Die Ganzzahl n wird bei jeder Iteration bzw. Anfrage um 1 erhöht.

Der Algorithmus ist so eingerichtet, dass er endet, wenn n = 5. Diese Obergrenze verhindert, dass die Clients unendlich fortfahren, und führt zu einer Verzögerung von insgesamt 32 Sekunden, bevor eine Anfrage als "nicht zu behebender Fehler" gilt. Sie können eine größere maximale Anzahl an Wiederholungen angeben, insbesondere wenn es sich um einen langen Upload handelt. Wichtig ist nur, dass die Wiederholungsverzögerung bei einem akzeptablen Wert liegt, zum Beispiel bei unter einer Minute.