Przesyłanie z możliwością wznowienia

Z tego artykułu dowiesz się, jak za pomocą interfejsu Street View Publish API poprosić o możliwość wznowienia przesyłania. Ten protokół umożliwia wznowienie operacji przesyłania po tym, jak błąd komunikacji przerwie przepływ danych. Użyj tej opcji, jeśli:

  • przesyłasz duże pliki.
  • prawdopodobieństwo przerwania połączenia lub innego błędu transmisji jest wysokie (na przykład, jeśli przesyłasz plik z aplikacji mobilnej).

Przesyłanie z możliwością wznowienia może też zmniejszyć wykorzystanie przepustowości w przypadku awarii sieci, ponieważ nie trzeba od początku ponownie wznawiać przesyłania dużych plików.

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

Rozpoczynanie sesji przesyłania z możliwością wznowienia

Po uzyskaniu uploadUrl możesz rozpocząć sesję przesyłania, którą można wznowić:

  1. Utwórz prośbę POST do uploadUrl.

  2. Dodaj te nagłówki HTTP:

    • X-Goog-Upload-Protocol: ustaw na resumable.
    • X-Goog-Upload-Header-Content-Length: ustaw łączną liczbę bajtów danych pliku, które zostaną przeniesione w kolejnych żądaniach.
    • X-Goog-Upload-Header-Content-Type: ustaw na typ MIME danych pliku.
    • X-Goog-Upload-Command: ustaw na start.

  3. Prześlij prośbę.

Przykład: inicjowanie sesji przesyłania z możliwością wznowienia

Ten przykład pokazuje, jak rozpocząć sesję wznawianą, aby przesłać nowy plik. W tym przypadku jest to obraz, a łączna liczba bajtów w pliku to 4 200 000. Pamiętaj, że treść żądania jest pusta, dlatego nagłówek Content-Length ma wartość 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

Sekcja Zapisywanie adresu URL sesji, którą można wznowić, opisuje sposób obsługi odpowiedzi na żądanie, która inicjuje możliwą do wznowienia sesję przesyłania.

Zapisywanie adresu URL sesji, którą można wznowić

W odpowiedzi na żądanie wysłane w celu zainicjowania sesji przesyłania z możliwością wznowienia serwer zwróci kod stanu HTTP 200 OK z tym nagłówkiem:

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

Skopiuj i zapisz adres URL sesji, którą można wznowić, aby móc go użyć w kolejnych żądaniach.

Przykład: zapisywanie adresu URL sesji z możliwością wznowienia

Przykład poniżej zawiera odpowiedź z adresem URL sesji z możliwością wznowienia i wymogiem dokładności rozmiaru.

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łanie pliku

Są 2 sposoby przesyłania pliku z sesją, którą można wznowić:

  1. W jednym żądaniu. To podejście jest zwykle najlepsze, ponieważ wymaga mniejszej liczby żądań, a więc zapewnia lepszą wydajność.
  2. W kilku częściach. Skorzystaj z tego podejścia, jeśli:
    • Musisz zmniejszyć ilość danych przesyłanych w ramach jednego żądania. Może być to konieczne, gdy w przypadku poszczególnych żądań obowiązuje określony limit czasu.
    • Musisz podać dostosowany wskaźnik pokazujący postęp przesyłania.
    • Musisz wiedzieć, kiedy można bezpiecznie odrzucić dane.

Pojedyncze żądanie

Aby przesłać plik w ramach pojedynczego zgłoszenia:

  1. Utwórz POST do adresu URL sesji z możliwością 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 na upload, finalize.

  4. Prześ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 fragmentach:

  1. Utwórz POST do adresu URL sesji z możliwością wznowienia.
  2. Dodaj dane fragmentu do treści żądania. Tworzenie fragmentów w wielokrotnościach 2 MiB (mebibajtów), z wyjątkiem ostatniego fragmentu, który kończy przesyłanie. Aby przesyłanie było wydajne, zachowaj jak największy rozmiar fragmentu.

  3. Dodaj te nagłówki HTTP:

    • Content-Length: ustaw liczbę bajtów w kawałku.
    • X-Goog-Upload-Command: ustaw na upload. Dla ostatniego fragmentu ustaw wartość upload, finalize.
    • X-Goog-Upload-Offset: ustaw przesunięcie, z jakim powinny być zapisywane bajty. Pamiętaj, że bajty muszą być przesyłane szeregowo.

  4. Wyślij prośbę. Jeśli prośba o przesyłanie zostanie przerwana lub otrzymasz odpowiedź 5xx, wykonaj czynności opisane w sekcji Wznawianie przerwanego przesyłania.

  5. Powtórz kroki 1–4 w przypadku każdego pozostałego fragmentu pliku.

Przykład: przesyłanie pliku

Pojedyncze żądanie

Ten przykład pokazuje żądanie z możliwością wznowienia, które umożliwia przesłanie całego pliku JPEG o rozmiarach 4 200 000 bajtów w jednym żądaniu przy użyciu adresu URL sesji z możliwością 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 się powiedzie, otrzymasz kod stanu HTTP 200 OK.

Wiele kawałków

Poniższy przykład przedstawia wznawialne żądanie przesłania pliku JPEG o rozmiarze 4 200 000 bajtów w wielu porcjach z użyciem adresu URL sesji, którą można wznowić, i precyzyjnego rozmiaru uzyskanego w poprzednim kroku. W tym przykładzie rozmiar fragmentu wynosi 2097000 bajtów, czyli 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]

Wznawiam przerwane przesyłanie

Jeśli żądanie przesyłania zostanie przerwane lub otrzymasz kod stanu HTTP inny niż 200, prześlij zapytanie do serwera, aby dowiedzieć się, na ile przesyłanie się powiodło:

  1. Utwórz POST do adresu URL sesji z możliwością wznowienia.
  2. Ustaw wartość X-Goog-Upload-Command na query.
  3. Prześlij prośbę.

Serwer w odpowiedzi przesyła kod stanu HTTP 200 OK i aktualny rozmiar przesyłanych danych:

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

Następnie możesz wznowić przesyłanie od tego miejsca. Musisz wznowić przesyłanie od przesunięcia podanego przez serwer, chyba że wyślesz połączone polecenie przesyłania i finalizacji, w którym przypadku możesz wznowić przesyłanie od przesunięcia 0.

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