Na tej stronie opisano, jak przesłać prośbę o wznowienie przesyłania do interfejsu Google Photos Library API za pomocą protokołu REST. Ten protokół umożliwia wznowienie operacji przesyłania po przerwaniu przepływu danych z powodu błędu komunikacji.
Użyj opcji przesyłania możliwego do wznowienia, jeśli:
- Przesyłasz duże pliki.
- Prawdopodobieństwo przerw w działaniu sieci lub innych błędów transmisji jest wysokie (np. gdy 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.
Krok 1. Rozpoczęcie sesji przesyłania
Zainicjuj możliwą do wznowienia sesję przesyłania, wysyłając żądanie POST do https://photoslibrary.googleapis.com/v1/uploads. Prześlij plik za pomocą adresu URL przesyłania możliwego do wznowienia zwróconego w ramach tego żądania.
Żądanie POST musi zawierać te nagłówki:
| Pola nagłówka | |
|---|---|
Content-Length |
Ustaw jako 0, ponieważ treść żądania jest pusta. |
X-Goog-Upload-Command |
Ustaw jako: start. |
X-Goog-Upload-Content-Type |
Ustaw na typ MIME pliku, na przykład image/jpeg. |
X-Goog-Upload-Protocol |
Ustaw jako: resumable. |
X-Goog-Upload-Raw-Size |
Ustaw łączną liczbę bajtów danych plików do przesłania. |
Oto nagłówek żądania POST:
POST https://photoslibrary.googleapis.com/v1/uploads Authorization: Bearer oauth2-token Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: mime-type X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: bytes-of-file
Krok 2. Zapisywanie adresu URL sesji
Jeśli operacja się powiedzie, żądanie POST zwróci kod stanu HTTP 200 OK, w tym ten nagłówek.
X-Goog-Upload-URL: url-to-make-uploads-to X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes
Pole nagłówka x-goog-upload-chunk-granularity zawiera wyrównanie bajtów i dokładność rozmiaru wszystkich fragmentów danych wysyłanych przez klienta. Jeśli dane przesyłasz w wielu fragmentach, wszystkie pliki z wyjątkiem ostatniego przesyłania muszą być wielokrotnościami tej wartości. Oznacza to, że bajty przesłanego pliku muszą być zgodne z tą wartością. W ostatnim fragmencie możesz przesłać pozostałe bajty.
Pole nagłówka X-Goog-Upload-URL zawiera unikalny adres URL, którego należy używać do zakończenia przesyłania w przypadku wszystkich pozostałych żądań. Skopiuj i zapisz ten adres URL sesji z możliwością wznowienia, aby móc go używać w kolejnych żądaniach.
Krok 3. Prześlij plik
Są 2 sposoby przesyłania pliku z sesją, którą można wznowić:
- W jednym żądaniu: Takie podejście jest zwykle najlepsze, ponieważ wymaga wysłania mniejszej liczby żądań, a więc zapewnia lepszą wydajność.
-
W kilku częściach. W przypadku tego podejścia przesyłanie odbywa się w kilku żądaniach, dzieląc dane na części. Dane są dzielone na bloki o długości
x-goog-upload-chunk-granularity. W razie potrzeby żądania podzielone na fragmenty można ponowić.Użyj tego podejścia, jeśli:
- Musisz zmniejszyć ilość danych przesyłanych w ramach pojedynczego żądania. Może być to konieczne, gdy obowiązuje określony limit czasu dla poszczególnych próśb.
- 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:
- Utwórz żądanie
POSTna adres URL sesji, którą można wznowić. - Dodaj dane pliku do treści żądania.
Dodaj te nagłówki HTTP:
Content-Length: ustaw liczbę bajtów w pliku.X-Goog-Upload-Command: ustaw naupload, finalize.
Prześlij prośbę.
Jeśli żądanie przesyłania zostanie przerwane lub otrzymasz odpowiedź 5xx, postępuj zgodnie z instrukcjami w artykule Wznowienie przerwanego przesyłania.
Jeśli żądanie się powiedzie, w treści odpowiedzi otrzymasz kod stanu HTTP 200 OK i token przesyłania.
Utwórz ten element multimedialny za pomocą tego tokena przesyłania.
Wiele fragmentów
Aby przesłać plik w kilku częściach:
- Utwórz
POSTdo adresu URL sesji z możliwością wznowienia. -
Dodaj dane fragmentu do treści żądania.
Z wyjątkiem ostatniego fragmentu, który kończy przesyłanie, twórz pozostałe fragmenty jako wielokrotności akceptowanego rozmiaru. Aby przesyłanie było wydajne, rozmiar kawałków powinien być jak największy.
-
Dodaj te nagłówki HTTP:
Content-Length: ustaw liczbę bajtów we fragmencie.X-Goog-Upload-Command: ustaw wartość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 kolejno. Pierwszy przesunięcie to0.
- Prześlij prośbę.
Jeśli żądanie przesyłania zostanie przerwane lub otrzymasz odpowiedź
5xx, postępuj zgodnie z instrukcjami w artykule Wznowienie przerwanego przesyłania. - Powtórz te czynności w przypadku każdego pozostałego fragmentu pliku.
Jeśli żądanie się powiedzie, w treści odpowiedzi otrzymasz kod stanu HTTP 200 OK i token przesyłania.
Utwórz element multimedialny, korzystając z tego tokena przesyłania.
Przykład
Pojedyncze żądanie
Ten przykład pokazuje żądanie z możliwością wznowienia przesyłania pliku JPEG o rozmiarach 3 039 417 bajtów w pojedynczym żądaniu.
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
Odpowiedź zawiera adres URL przesyłania i oczekiwany rozmiar fragmentu:
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
Ostatnie żądanie przesłania:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 3039417 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 0 [BYTES 0-4199999]
Wiele kawałków
Poniższy przykład przedstawia wznawialne żądanie przesłania wielu fragmentów pliku JPEG o rozmiarze 3 039 417 bajtów z użyciem adresu URL sesji, którą można wznowić, i akceptowanego rozmiaru fragmentu uzyskanego w poprzednim kroku.
W tym przykładzie rozmiar fragmentu wynosi 262 144 bajty, co zostało zwrócone w polu nagłówka x-goog-upload-chunk-granularity podczas inicjowania sesji przesyłania. Pamiętaj, że każdy przesyłany plik zawiera bajty, które są wielokrotnością 262 144.
Zainicjuj sesję przesyłania, aby otrzymać adres URL przesyłania i rozmiar części, jak opisano w poprzednim kroku:
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
Odpowiedź zawiera adres URL przesyłania i oczekiwany rozmiar fragmentu:
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
Pierwszy fragment:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 0 [BYTES 0-1048575]
Drugi fragment:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 1048576 [BYTES 1048576-2097151]
Ostatni fragment:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 942265 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 2097152 [BYTES 2097152-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.
Oto żądanie POST na URL sesji, którą można wznowić. X-Goog-Upload-Commandpowinno mieć wartość query.
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: query
Odpowiedź serwera zawiera kod stanu HTTP 200 OK i bieżący rozmiar 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 na polecenie zapytania występuje nagłówek X-Goog-Upload-Status, a jego wartość nie jest active, oznacza to, że przesyłanie zostało już zakończone.