Na tej stronie dowiesz się, jak wysłać żądanie przesyłania z możliwością wznowienia w interfejsie Street View Publish API. Ten protokół umożliwia wznowienie przesyłania po przerwaniu przepływu danych z powodu awarii komunikacji. Użyj tej opcji, jeśli:
- przesyłasz duże pliki;
- Prawdopodobieństwo przerwania połączenia sieciowego lub innego błędu transmisji jest wysokie (np. podczas przesyłania pliku z aplikacji mobilnej).
Wznawialne przesyłanie może też zmniejszyć wykorzystanie przepustowości w przypadku awarii sieci, ponieważ nie musisz ponownie przesyłać dużych plików od początku.
Jeśli wysyłasz małe pliki przez niezawodne połączenie sieciowe, 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 z możliwością wznowienia:
- Utwórz
POSTprośbę douploadUrl. Dodaj te nagłówki HTTP:
X-Goog-Upload-Protocol: ustaw wartośćresumable.X-Goog-Upload-Header-Content-Length: ustawiona na łączną liczbę bajtów danych pliku, które zostaną przesłane w kolejnych żądaniach.X-Goog-Upload-Header-Content-Type: Ustaw na typ MIME danych pliku.X-Goog-Upload-Command: ustaw wartośćstart.
Wyślij prośbę.
Przykład: rozpoczynanie sesji przesyłania z możliwością wznowienia
Poniższy 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 wynosi 4200000. Pamiętaj, że treść żądania jest pusta, dlatego 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
W sekcji Zapisywanie adresu URL sesji z możliwością wznowienia opisujemy, jak obsługiwać odpowiedź na żądanie rozpoczęcia sesji przesyłania z możliwością wznowienia.
Zapisywanie adresu URL sesji z możliwością wznowienia
W przypadku żądania wysłanego w celu zainicjowania sesji przesyłania z możliwością wznowienia serwer odpowie kodem stanu HTTP 200 OK, w tym tym nagłówkiem:
X-Goog-Upload-URL: unikalny adres URL, którego należy użyć do przesłania pliku we wszystkich pozostałych żądaniach.
Skopiuj i zapisz adres URL sesji z możliwością wznowienia, aby użyć go w kolejnych żądaniach.
Przykład: zapisywanie adresu URL sesji z możliwością wznowienia
Poniższy przykład pokazuje odpowiedź, która zawiera adres URL sesji z możliwością wznowienia i wymaganie dotyczące szczegółowoś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żesz przesłać w sesji możliwej do wznowienia na 2 sposoby:
- W jednym żądaniu. To podejście jest zwykle najlepsze, ponieważ wymaga mniejszej liczby żądań, a tym samym zapewnia lepszą skuteczność.
- W wielu częściach. Skorzystaj z tej metody, jeśli:
- Musisz zmniejszyć ilość danych przesyłanych w ramach jednego żądania. Może to być konieczne, gdy poszczególne żądania mają stały 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 jednego żądania:
- Utwórz
POSTżądanie do adresu URL sesji z możliwością wznowienia. - Dodaj dane pliku do treści żądania.
Dodaj te nagłówki HTTP:
Content-Length: ustawiona na liczbę bajtów w pliku.X-Goog-Upload-Command: ustaw wartośćupload, finalize.
Wyślij prośbę.
Jeśli żądanie przesłania zostanie przerwane lub otrzymasz odpowiedź 5xx, postępuj zgodnie z procedurą opisaną w sekcji Wznawianie przerwanego przesyłania.
Wiele części
Aby przesłać plik w kilku częściach:
- Utwórz
POSTżądanie do adresu URL sesji z możliwością wznowienia. - Dodaj dane fragmentu do treści żądania. Twórz części w wielokrotnościach 2 MiB (mebibajtów), z wyjątkiem ostatniej części, która kończy przesyłanie. Utrzymuj jak największy rozmiar fragmentu, aby przesyłanie było wydajne.
Dodaj te nagłówki HTTP:
Content-Length: ustawiona na liczbę bajtów w bloku.X-Goog-Upload-Command: ustaw wartośćupload. W przypadku ostatniego fragmentu ustaw wartośćupload, finalize.X-Goog-Upload-Offset: Ustaw na przesunięcie, od którego mają być zapisywane bajty. Pamiętaj, że bajty muszą być przesyłane szeregowo.
Wyślij prośbę. Jeśli żądanie przesłania zostanie przerwane lub otrzymasz odpowiedź
5xx, postępuj zgodnie z procedurą opisaną w sekcji Wznawianie przerwanego przesyłania.Powtórz kroki od 1 do 4 dla każdego pozostałego fragmentu pliku.
Przykład: przesyłanie pliku
Pojedyncze żądanie
Poniższy przykład pokazuje żądanie z możliwością wznowienia, które umożliwia przesłanie całego pliku JPEG o rozmiarze 4 200 000 bajtów w ramach jednego żądania 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 zostanie zrealizowane, otrzymasz kod stanu HTTP 200 OK.
Wiele części
Poniższy przykład pokazuje żądanie z możliwością wznowienia przesyłania pliku JPEG o rozmiarze 4 200 000 bajtów w kilku częściach przy użyciu adresu URL sesji z możliwością wznowienia i granulacji rozmiaru uzyskanej w poprzednim kroku. W tym przykładzie używamy rozmiaru fragmentu wynoszącego 2097000 bajtów, czyli 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 przerwanego przesyłania
Jeśli żądanie przesłania zostanie przerwane lub otrzymasz kod stanu HTTP inny niż 200, wyślij zapytanie do serwera, aby dowiedzieć się, jaka część przesyłania się powiodła:
- Utwórz
POSTżądanie do adresu URL sesji z możliwością wznowienia. - Ustaw wartość
X-Goog-Upload-Commandnaquery. - Wyś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 przesunięcia. Musisz wznowić przesyłanie od przesunięcia podanego przez serwer, chyba że wyślesz połączone polecenie przesyłania i finalizacji. W takim przypadku możesz też wznowić przesyłanie od przesunięcia 0.
Jeśli w odpowiedzi HTTP na polecenie zapytania występuje nagłówek X-Goog-Upload-Status, a jego wartość nie jest równa active, przesyłanie zostało już zakończone.