Utwórz pakiet

Opcje przesyłania

Interfejs Android Over The Air API umożliwia przesyłanie danych pakietu w celu utworzenia nowego zasobu pakietu. Są to Pakiety OTA, które można powiązać z co najmniej 1 konfiguracją, aby dostarczyć aktualizację. do urządzeń.

Udostępniamy plik binarny dla systemów Linux i Windows, aby ułatwić wznawianie przesyłania pakietów są bezpłatne i nie trzeba stosować opisanych poniżej protokołów. Jeśli chcesz wiedzieć więcej należy użyć jednego z protokołów opisanych poniżej.

Linux

Pobierz klienta interfejsu Android Over The Air API w wersji 1 do przesyłania dla systemu Linux.

Windows

Pobierz klienta interfejsu Android Over The Air API w wersji 1 do przesyłania danych dla systemu Windows.

Aby z niego korzystać, musisz najpierw utworzyć konto usługi i uzyskać dla niego plik klucza JSON. Tutaj znajdziesz przewodnik po tworzeniu konta.
Plik binarny i plik klucza możesz uruchomić, używając opcji wiersza poleceń, aby określić plik z kluczem, wdrożenie i przesyłany pakiet. Użyj konta --help aby zobaczyć wszystkie opcje.

Protokoły przesyłania

Prośby o przesłanie możesz przesłać na dowolny z poniższych sposobów. W nagłówku żądania X-Goog-Upload-Protocol określ używaną metodę.

  • Przesyłanie wieloczęściowe: X-Goog-Upload-Protocol: multipart. Aby szybko przenieść mniejsze pliki i metadane, przesyła plik wraz z opisującymi go metadanymi, a wszystko to w ramach jednego żądania.
  • Przesyłanie z możliwością wznowienia: X-Goog-Upload-Protocol: resumable. Niezawodne przesyłanie danych, szczególnie w przypadku większych . Ta metoda wykorzystuje żądanie inicjujące sesję, które może opcjonalnie zawierać metadane. Strategia ta jest przydatna dla większości aplikacji, bo pozwala to też na obsługę mniejszych plików, co wymaga opłaty za jedno dodatkowe żądanie HTTP przy każdym przesłaniu.

Przesyłanie wieloczęściowe

Jest to dobry wybór, jeśli przesyłane dane są małe tyle, aby przesłać je w całości w przypadku braku połączenia.

Aby użyć przesyłania wieloczęściowego, wyślij żądanie POST do pliku /upload/package Identyfikator URI i ustaw X-Goog-Upload-Protocol na multipart.

Nagłówki HTTP najwyższego poziomu, których należy użyć w przypadku wysyłania wieloczęściowego żądania przesyłania, to między innymi:

  • Content-Type Ustaw jako wieloczęściową/powiązaną i uwzględnij ciąg granicy, w której za pomocą której można zidentyfikować te części żądania.
  • Content-Length Ustaw łączną liczbę bajtów w treści żądania.

Treść żądania jest sformatowana jako treść multipart/related typu [RFC2387] i zawiera dokładnie 2 części. Części są oznaczone ciągiem znaków granicy, a po nim końcowym – 2 łączniki.

Każda część żądania wieloczęściowego wymaga dodatkowego nagłówka Content-Type:

  1. Część metadanych: wartość musi być pierwsza, a pole Content-Type musi mieć wartość application/json.
  2. Część multimediów: musi być druga, a Content-Type musi mieć wartość application/zip.

Przykład: przesyłanie wieloczęściowe

Przykład poniżej przedstawia wieloczęściowe żądanie przesłania danych przez interfejs 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--

Jeśli żądanie zostanie zrealizowane, serwer zwróci kod stanu HTTP 200 OK

HTTP/1.1 200

Aby to łatwo zrobić, użyj polecenia curl i oauth2l. Poniżej znajduje się przykładowe żądanie , który zakłada, że używasz klucza usługi (zobacz jak uzyskać autoryzację).

Przykładowe żądanie curl 
    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

Przesyłanie z możliwością wznowienia

Aby zwiększyć niezawodność przesyłania plików danych, możesz użyć protokołu przesyłania z możliwością wznawiania. Protokół ten umożliwia wznowienie operacji przesyłania po przerwaniu przepływu danych przez błąd komunikacji. it jest szczególnie przydatna, gdy przesyłasz duże pliki i istnieje ryzyko przerw w działaniu sieci lub występują inne błędy transmisji, które występują podczas przesyłania, np. z aplikacji klienta mobilnej. it może też zmniejszyć wykorzystanie przepustowości w przypadku awarii sieci, ponieważ nie trzeba przesyłać duże pliki od początku.

Protokół przesyłania z możliwością wznowienia używa kilku poleceń:

  1. Rozpocznij sesję, którą można wznowić. Wyślij wstępne żądanie do identyfikatora URI przesyłania zawierającego metadanych i ustanawia unikalną lokalizację przesyłania, którą można wznowić.
  2. Zapisz identyfikator URI sesji, którą można wznawiać. Zapisz identyfikator URI sesji zwrócony w odpowiedź na pierwotne żądanie; Użyjesz go w pozostałych żądaniach w tej sesji.
  3. Prześlij plik. Wyślij całość lub część pliku ZIP do identyfikatora URI sesji możliwej do wznowienia.

Oprócz tego aplikacje korzystające z funkcji wznawiania przesyłania muszą mieć kod umożliwiający wznawianie przerwanego przesyłania. Jeśli przesyłany film jest aby sprawdzić, ile danych udało się odebrać, i wznowić przesyłanie, zaczynając od tego momentu.

Uwaga: identyfikator URI przesyłania wygasa po 3 dniach.

Krok 1. Rozpocznij sesję, którą można wznowić

Aby rozpocząć przesyłanie, które można wznowić, wyślij żądanie POST do pliku /upload/package. Identyfikator URI i ustaw X-Goog-Upload-Protocol na resumable.

Treść tego żądania inicjującego musi zawierać tylko metadane. przenosisz rzeczywistość zawartość pliku, który chcesz przesłać w kolejnych żądaniach.

W pierwszym żądaniu HTTP użyj tych nagłówków HTTP:

  • X-Goog-Upload-Header-Content-Type To jest typ treści przesyłanego pliku i musi być ustawiony na application/zip.
  • X-Goog-Upload-Command Ustaw jako start
  • X-Goog-Upload-Header-Content-Length Ustaw liczbę bajtów przesyłanych danych, które mają być przeniesione w kolejnych żądaniach. Jeśli długość jest nieznana w momencie wysyłania żądania, możesz pominąć ten nagłówek.
  • Content-Type Jest to typ treści metadanych, który musi być ustawiony na application/json.
  • Content-Length Ustaw liczbę bajtów podanych w treści tego początkowego żądania.
Przykład: żądanie zainicjowania sesji z możliwością wznowienia

Z przykładu poniżej dowiesz się, jak rozpocząć sesję wznawianą w przypadku interfejsu Android Over The Air API.

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" }

W następnej sekcji dowiesz się, jak postępować z odpowiedzią.

Krok 2. Zapisz identyfikator URI sesji do wznawiania

Jeśli żądanie zainicjowania sesji zostanie zrealizowane, serwer interfejsu API w odpowiedzi przesyła kod stanu HTTP 200 OK. Oprócz tego zawiera nagłówek X-Goog-Upload-URL, który określa identyfikator URI sesji do wznowienia. Nagłówek X-Goog-Upload-URL widoczny w przykładzie poniżej zawiera parametr zapytania upload_id , która określa unikalny identyfikator przesyłania używany w danej sesji. Odpowiedź zawiera też atrybut X-Goog-Upload-Status nagłówek, czyli active, jeśli żądanie przesyłania było prawidłowe i zaakceptowane. Ten stan może być ustawiony na final jeśli przesyłanie zostało odrzucone.

Przykład: odpowiedź na zainicjowanie sesji z możliwością wznawiania

Oto odpowiedź na żądanie z kroku 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

Wartość nagłówka X-Goog-Upload-URL (pokazana w powyższej przykładowej odpowiedzi) to identyfikator URI sesji, który będzie używany jako punkt końcowy HTTP do przesyłania rzeczywistego pliku lub wysyłania zapytań o stan przesyłania.

Skopiuj i zapisz identyfikator URI sesji, by móc go używać w kolejnych żądaniach.

Krok 3: prześlij plik

Aby przesłać plik, wyślij żądanie POST pod identyfikator URI przesyłania uzyskany w poprzedniego kroku. Prośba o przesłanie pliku jest w formacie:

POST session_uri

Nagłówki HTTP używane przy wysyłaniu żądań przesyłania plików z możliwością wznawiania obejmują:

  1. Content-Length Ustaw tę wartość na liczbę bajtów, które chcesz przesłać w ramach tego żądania. Jest to zwykle rozmiar przesyłanego pliku.
  2. X-Goog-Upload-Command Ustaw na upload i finalize.
  3. X-Goog-Upload-Offset Określało przesunięcie, od którego należy zapisywać bajty. Pamiętaj, że klienci musi przesyłać bajty po kolei.
Przykład: żądanie wznowienia przesłania pliku

To jest możliwe do wznowienia żądanie przesłania całego pliku ZIP o rozmiarze 2 000 000 bajtów w obecnym przykładzie.

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

Jeśli żądanie zostanie zrealizowane, serwer zwróci odpowiedź HTTP 200 Ok.

Jeśli żądanie przesyłania zostanie przerwane albo otrzymasz żądanie HTTP 503 Service Unavailable lub inne innej odpowiedzi 5xx z serwera, wykonaj procedurę opisaną w sekcji Wznów przerwane przesyłanie.

Przesyłanie pliku etapami

Dzięki wznawianiu przesyłania możesz podzielić plik na fragmenty i wysłać serię żądań, aby przesłać każdy fragment po kolei. Nie jest to preferowane podejście, ponieważ dodatkowe żądania wiążą się z kosztami. jest zwykle zbędne. Zalecamy, aby klienty przesłały wszystkie pozostałe bajty ładunku do każdego polecenia upload dodaj polecenie finalize.

Może być jednak konieczne podział na fragmenty, aby zmniejszyć ilość danych przesyłanych w dowolnym tylko jedno żądanie. Pozwala też na przykład wyświetlać wskaźniki postępu przesyłania w starszych przeglądarkach. które domyślnie nie mają obsługi postępu przesyłania.

Wznawianie przerwanego przesyłania

Jeśli żądanie przesyłania zostanie zakończone przed otrzymaniem odpowiedzi lub gdy otrzymasz odpowiedź HTTP 503 Service Unavailable z serwera, musisz wznowić przerwane przesyłanie. Aby to zrobić:

  1. Stan żądania. Wysyłanie zapytania do identyfikatora URI przesyłania, aby sprawdzić bieżący stan przesyłania z polem X-Goog-Upload-Command ustawionym na wartość query.

    Uwaga: możesz sprawdzać stan poszczególnych fragmentów nie tylko w przypadku przerwania przesyłania. To jest przydatny na przykład wtedy, gdy chcesz wyświetlać informacje o postępie przesyłania w starszych przeglądarkach.

  2. Sprawdź liczbę przesłanych bajtów. Przetwórz odpowiedź z zapytania o stan. Serwer używa nagłówek X-Goog-Upload-Size-Received w odpowiedzi z informacją, ile bajtów otrzymał do tej pory.
  3. Prześlij pozostałe dane. Wiesz już, gdzie wznowić prośbę, prześlij lub bieżący fragment. Pamiętaj, że w obu przypadkach musisz traktować pozostałe dane jako oddzielny fragment, więc po wznowieniu przesyłania musisz ustawić w nagłówku X-Goog-Upload-Offset odpowiednie przesunięcie.
Przykład: wznawianie przerwanego przesyłania

1) Poproś o stan przesyłania.

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

Tak jak w przypadku wszystkich poleceń, klient musi sprawdzić nagłówek X-Goog-Upload-Status w odpowiedzi HTTP polecenia zapytania. Jeśli nagłówek jest obecny, a wartość nie jest ustawiona na active, przesyłanie zostało już zakończone.

2) Pobierz z odpowiedzi liczbę przesłanych do tej pory bajtów.

W odpowiedzi serwera używany jest nagłówek X-Goog-Upload-Size-Received w celu zasygnalizowania, że odebrano do tej pory pierwsze 43 bajty pliku.

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

3) Wznów przesyłanie od miejsca, w którym zostało przerwane.

Kolejne żądanie wznowi przesyłanie, wysyłając pozostałe bajty pliku, zaczynając od bajtu 43.

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

Sprawdzone metody

Podczas przesyłania multimediów warto pamiętać o kilku sprawdzonych metodach dotyczących obsługi błędów.

  • Wznów lub ponów przesyłanie, które nie powiodło się z powodu przerw w połączeniu lub błędów 5xx, w tym:
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • Jeśli podczas wznawiania lub ponawiania żądań przesyłania wystąpi dowolny błąd serwera 5xx, użyj strategii wykładniczego ponowienia. Te błędy mogą wystąpić, jeśli serwer jest przeciążony. Wykładniczy czas do ponowienia może pomóc łagodzić tego typu problemy w okresach dużej liczby żądań lub dużego ruchu w sieci.
  • Inne rodzaje żądań nie powinny być obsługiwane przez wykładniczy czas do ponowienia, ale nadal możesz ponawiać kilka prób. Jeśli chcesz ponawiać te żądania, ogranicz liczbę ponownych prób. Na przykład przed zgłoszeniem błędu kod może mieć maksymalnie 10 ponownych prób.
  • Podczas przesyłania z możliwością wznowienia usuń błędy 404 Not Found, rozpoczynając przesyłanie od początku.

Wykładniczy czas do ponowienia

Wykładniczy czas ponowienia to standardowa strategia obsługi błędów w aplikacjach sieciowych, w których klient okresowo ponawia nieudane żądanie w coraz większym czasie. Jeśli z powodu dużej liczby żądań lub dużego ruchu sieciowego serwer zwraca błędy, dobrym rozwiązaniem będzie stosowanie wykładniczego czasu do ponowienia. Z drugiej strony nie jest to odpowiednia strategia w przypadku błędów niezwiązanych z ilością sieci czy czasem reakcji, takimi jak nieprawidłowe dane uwierzytelniające autoryzacji lub błędy „Nie znaleziono pliku”.

Prawidłowo używany, rosnący wykładniczy czas ponowienia zwiększa wydajność wykorzystania przepustowości, zmniejsza liczbę żądań wymaganych do uzyskania pomyślnej odpowiedzi i maksymalizuje przepustowość żądań w środowiskach równoczesnych.

Proces implementacji prostego wzrastającego czasu do ponowienia jest następujący:

  1. Wyślij żądanie do interfejsu API.
  2. Otrzymasz odpowiedź HTTP 503, która oznacza, że należy ponowić żądanie.
  3. Odczekaj 1 sekundę + los_number_milliseconds i spróbuj ponownie.
  4. Otrzymasz odpowiedź HTTP 503, która oznacza, że należy ponowić żądanie.
  5. Odczekaj 2 sekundy + random_number_milliseconds i spróbuj ponownie.
  6. Otrzymasz odpowiedź HTTP 503, która oznacza, że należy ponowić żądanie.
  7. Odczekaj 4 sekundy + random_number_milliseconds i spróbuj ponownie.
  8. Otrzymasz odpowiedź HTTP 503, która oznacza, że należy ponowić żądanie.
  9. Odczekaj 8 sekund + los_number_milliseconds i spróbuj ponownie.
  10. Otrzymasz odpowiedź HTTP 503, która oznacza, że należy ponowić żądanie.
  11. Odczekaj 16 sekund + los_number_milliseconds i spróbuj ponownie.
  12. Zatrzymaj. Zgłoś lub zapisz błąd.

W tym przykładzie losowo_liczba_milisekund to losowa liczba milisekund mniejsza lub równa 1000. Jest to konieczne, ponieważ wprowadzenie niewielkiego losowego opóźnienia pomaga bardziej równomiernie rozłożyć obciążenie i uniknąć możliwości „przytłoczenia” serwera. Po każdym oczekiwaniu należy ponownie zdefiniować wartość parametru random_number_milliseconds.

Uwaga: oczekiwanie to zawsze (2 ^ n) + losowa_liczba_milisekund, gdzie n to monotonicznie rosnąca liczba całkowita zdefiniowana początkowo jako 0. Liczba całkowita n zwiększa się o 1 dla każdej iteracji (każdego żądania).

Algorytm wyłącza się, gdy n = 5. Taki limit uniemożliwia klientom ponawianie prób w nieskończoność i powoduje, że żądanie zostaje uznane za „błąd nieodwracalny” wynoszący około 32 sekundy. Większa maksymalna liczba ponownych prób to dobre rozwiązanie, zwłaszcza w przypadku długiego przesyłania. pamiętaj, aby ograniczyć opóźnienie ponawiania do rozsądnej, na przykład niecałej minuty.