Przesyłanie z możliwością wznowienia

Na tej stronie znajdziesz informacje o tym, jak przesłać prośbę o przerwane przesyłanie w interfejsie Street View Publish API. 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 wtedy ponownie rozpoczynać 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 zainicjować sesję z możliwością wznowienia, aby przesłać nowy plik. W tym przypadku plik jest obrazem, a łączna liczba bajtów w pliku to 4200000. 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

Zapisywanie adresu URL sesji z możliwością wznowienia zawiera opis sposobu obsługi odpowiedzi na żądanie rozpoczęcia sesji przesyłania z możliwością wznowienia.

Zapisywanie adresu URL sesji z możliwością wznowienia

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 wymaganiem dotyczącym 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

Plik można przesłać w ramach sesji możliwej do wznowienia na 2 sposoby:

  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 pojedynczego żą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 żądanieWiele kawałków

Aby przesłać plik w jednym żądaniu:

  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: liczba 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.

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

  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. W przypadku ostatniego fragmentu ustaw wartość upload, finalize.
    • X-Goog-Upload-Offset: ustaw przesunięcie, w którym mają być zapisane bajty. Pamiętaj, że bajty muszą być przesyłane szeregowo.

  4. Prześlij prośbę. Jeśli żądanie przesyłania zostanie przerwane lub otrzymasz odpowiedź 5xx, postępuj zgodnie z instrukcjami w artykule Wznawianie przerwanego przesyłania.

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

Przykład: przesyłanie pliku

Pojedyncze żądanieWiele kawałków

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.

W tym przykładzie pokazano prośbę o wstrzymane przesyłanie pliku JPEG o rozmiary 4 200 000 bajtów w kilku częściach, przy użyciu adresu URL sesji z możliwością wznowienia i rozdzielenia rozmiaru na mniejsze części 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]

Wznowienie przerwanego przesyłania

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 odpowie kodem stanu HTTP 200 OK i bieżącym rozmiarem przesyłanego pliku:

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 zapytania zawiera nagłówek X-Goog-Upload-Status, a jego wartość nie jest równa active, oznacza to, że przesyłanie zostało już przerwane.