Przesyłanie z możliwością wznowienia

Na tej stronie opisujemy, jak za pomocą interfejsu Street View Publish API utworzyć żądanie wznowienia przesyłania. Protokół ten umożliwia wznowienie operacji przesyłania, gdy przepływ danych zostanie przerwany przez błąd komunikacji. Użyj tej opcji, jeśli:

  • Przesyłasz duże pliki.
  • Prawdopodobieństwo przerw w działaniu sieci lub innych awarii transmisji jest wysokie (na przykład wtedy, gdy przesyłasz plik z aplikacji mobilnej).

Wznawianie przesyłania może też zmniejszyć wykorzystanie przepustowości w przypadku awarii sieci, ponieważ nie trzeba ponownie uruchamiać dużych plików.

Jeśli wysyłasz małe pliki przez stabilne połączenie sieciowe, możesz użyć prostego przesyłania.

Rozpoczynam sesję przesyłania z możliwością wznowienia

Gdy uzyskasz uploadUrl, możesz zainicjować sesję przesyłania z możliwością wznowienia:

  1. Utwórz żądanie POST do: uploadUrl.

  2. Dodaj te nagłówki HTTP:

    • X-Goog-Upload-Protocol: ustaw wartość resumable.
    • X-Goog-Upload-Header-Content-Length: ustaw łączną liczbę bajtów danych, które będą przesyłane w kolejnych żądaniach.
    • X-Goog-Upload-Header-Content-Type: ustaw typ MIME danych pliku.
    • X-Goog-Upload-Command: ustaw wartość start.

  3. Wyślij prośbę.

Przykład: inicjowanie sesji przesyłania możliwej do wznowienia

Z przykładu poniżej dowiesz się, jak zainicjować sesję z możliwością wznowienia, aby przesłać nowy plik. W tym przypadku jest to obraz, a łączna liczba bajtów w pliku wynosi 4 200 000. Pamiętaj, że treść żądania jest pusta, więc nagłówek Content-Length jest ustawiony na 0.

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234 HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Length: 0
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Header-Content-Length: 4200000
X-Goog-Upload-Header-Content-Type: image/jpeg
X-Goog-Upload-Command: start

Zapisywanie adresu URL sesji możliwej do wznowienia zawiera informacje o sposobie obsługi odpowiedzi na żądanie, które powoduje zainicjowanie sesji przesyłania możliwej do wznowienia.

Zapisuję URL sesji możliwej do wznowienia

Na żądanie wysłane w celu zainicjowania sesji przesyłania możliwej do wznowienia serwer w odpowiedzi wysyła kod stanu HTTP 200 OK zawierający ten nagłówek:

  • X-Goog-Upload-URL: unikalny adres URL, którego trzeba użyć do zakończenia przesyłania pozostałych żądań.

Skopiuj i zapisz adres URL wznowienia, aby móc go używać w kolejnych żądaniach.

Przykład: zapisywanie adresu URL sesji możliwej do wznowienia

Poniższy przykład pokazuje odpowiedź zawierającą adres URL sesji, który można wznowić, oraz wymagany poziom szczegółowości.

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable

Przesyłam plik

Plik z sesją, którą można wznowić, można przesłać na 2 sposoby:

  1. W jednej prośbie. Ten sposób zwykle jest najlepszy, ponieważ wymaga mniejszej liczby żądań i w rezultacie jest skuteczniejszy.
  2. W kilku częściach. Zastosuj tę metodę, jeśli:
    • Musisz zmniejszyć ilość danych przesyłanych w jednym żądaniu. Może to być konieczne, gdy istnieje stały limit czasu dla poszczególnych żądań.
    • Musisz dodać niestandardowy wskaźnik postępu przesyłania.
    • Musisz wiedzieć, kiedy można bezpiecznie odrzucić dane.

Pojedyncze żądanie

Aby przesłać plik w jednej prośbie:

  1. Utwórz żądanie POST na adres URL sesji możliwej do wznowienia.
  2. Dodaj dane pliku do treści żądania.

  3. Dodaj te nagłówki HTTP:

    • Content-Length: ustaw liczbę bajtów w pliku.
    • X-Goog-Upload-Command: ustaw wartość upload, finalize.

  4. Wyślij prośbę.

Jeśli żądanie przesyłania zostanie przerwane lub otrzymasz odpowiedź 5xx, wykonaj czynności opisane w sekcji Wznawianie przerwanego przesyłania.

Wiele kawałków

Aby przesłać plik w kilku częściach:

  1. Utwórz żądanie POST na adres URL sesji możliwej do wznowienia.
  2. Dodaj dane fragmentu do treści żądania. Utwórz fragmenty w wielobajtach po 2 MiB (mebibajty) z wyjątkiem ostatniego fragmentu, który kończy przesyłanie. Aby przesyłanie przebiegało sprawnie, pilnuj, by fragmenty były jak największe.

  3. Dodaj te nagłówki HTTP:

    • Content-Length: ustaw liczbę bajtów we fragmencie.
    • X-Goog-Upload-Command: ustaw wartość upload. Dla ostatniego fragmentu ustaw wartość upload, finalize.
    • X-Goog-Upload-Offset: ustaw przesunięcie, po którym mają być zapisywane bajty. Pamiętaj, że bajty muszą być przesłane po kolei.

  4. Wyślij prośbę. Jeśli żądanie przesyłania zostanie przerwane lub otrzymasz odpowiedź 5xx, wykonaj czynności opisane w sekcji Wznawianie przerwanego przesyłania.

  5. Powtarzaj kroki od 1 do 4 w przypadku każdego pozostałego fragmentu pliku.

Przykład: przesyłanie pliku

Pojedyncze żądanie

Ten przykład przedstawia możliwe do wznowienia żądanie przesłania całego pliku JPEG o wielkości 4 200 000 bajtów w jednym żądaniu przy użyciu adresu URL sesji możliwej do wznowienia uzyskanego w poprzednim kroku:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 4200000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

Jeśli żądanie zostanie zrealizowane, otrzymasz kod stanu HTTP 200 OK.

Wiele kawałków

Poniższy przykład przedstawia żądanie wznowienia przesyłania pliku JPEG o rozmiarze 4 200 000 bajtów w wielu fragmentach przy użyciu adresu URL sesji możliwej do wznowienia i szczegółowości uzyskanej w poprzednim kroku. W tym przykładzie użyto fragmentu 20 97 000 bajtów, który jest wielokrotnością 2 MiB (mebibajtów).

Pierwszy fragment: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0



[BYTES 0-2096999]

Drugi fragment: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 2097000



[BYTES 2097000-4193999]

Ostatni fragment:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 6000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 4194000



[BYTES 4194000-4200000]

Wznawianie przesyłania przerwanego

Jeśli żądanie przesyłania zostało przerwane lub otrzymasz kod stanu HTTP inny niż 200, wyślij do serwera zapytanie, aby dowiedzieć się, jaka część przesłanych plików się powiodła:

  1. Utwórz żądanie POST na adres URL sesji możliwej do wznowienia.
  2. Ustaw wartość X-Goog-Upload-Command na query.
  3. Wyślij prośbę.

Serwer w odpowiedzi prześle kod stanu HTTP 200 OK i bieżący rozmiar przesyłanych plików:

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

Potem możesz wznowić przesyłanie. Musisz wznowić działanie po stronie kompensacji podanej przez serwer, chyba że wyślesz połączone polecenie przesyłania i finalizacji. W takim przypadku możesz wznowić pracę od przesunięcia 0.

Jeśli nagłówek X-Goog-Upload-Status w odpowiedzi HTTP polecenia zapytania występuje, a jego wartość nie jest ustawiona na active, przesyłanie zostało już zakończone.