Na tej stronie dowiesz się, jak wysłać żądanie wznowienia przesyłania do interfejsu Google Photos Library API za pomocą protokołu REST. Ten protokół umożliwia wznowienie operacji przesyłania gdy awaria komunikacji przerwie przepływ danych.
Użyj opcji przesyłania z możliwością wznawiania, jeśli:
- Przesyłasz duże pliki.
- Prawdopodobieństwo przerwy w działaniu sieci lub innych problemów z transmisją jest (jeśli na przykład przesyłasz plik z aplikacji mobilnej).
Wznawianie przesyłania może też zmniejszyć wykorzystanie przepustowości w przypadku połączenia z siecią ponieważ nie trzeba ponownie uruchamiać przesyłania dużych plików od początku.
Krok 1. Inicjowanie sesji przesyłania
Zainicjuj możliwą do wznowienia sesję przesyłania, wysyłając żądanie POST do
https://photoslibrary.googleapis.com/v1/uploads Korzystanie z przesyłania z możliwością wznowienia
Adres URL zwrócony w tym żądaniu. Prześlij plik.
Żą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 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 pliku przeniesione. |
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ę uda, żądanie POST zwróci kod stanu HTTP 200 OK zawierający kod stanu HTTP 200 OK,
następujący 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 szczegółowość rozmiaru dla wszystkich fragmentów danych wysyłanych przez klienta. Jeśli przesyłanie odbywa się w wiele częściach, wszystkie przesyłane dane (z wyjątkiem ostatniego) muszą być wielokrotnością tej wartości. Oznacza to, że liczba przesyłanych bajtów pliku
musi być wyrównana do tej wartości. W ostatnim fragmencie możesz przesłać pozostałe
B.
Pole nagłówka X-Goog-Upload-URL zawiera unikalny adres URL, który musi służyć do
wykonać wszystkie pozostałe żądania. Skopiuj i zapisz to
adresu URL sesji, który można wznowić, aby używać go w kolejnych żądaniach.
Krok 3. Prześlij plik
Są 2 sposoby przesyłania pliku z sesją, którą można wznowić:
- W jednym żądaniu: Ta metoda jest zwykle najlepsza, ponieważ wymaga mniejszej liczby żądań i tym samym ma większą wydajność.
-
W kilku fragmentach. W przypadku tego podejścia przesyłanie odbywa się w kilku żądaniach przez podzielenie danych na części. Dane są podzielone na fragmenty wielokrotności
x-goog-upload-chunk-granularity. W razie potrzeby: żądania podzielone na fragmenty można ponowić.Skorzystaj z tej metody, jeśli:
- Musisz zmniejszyć ilość danych przesyłanych w jednym użytkownika. Może to być konieczne, gdy obowiązuje ustalony limit czasu indywidualnych żądań.
- Musisz podać własny wskaźnik pokazujący, że przesyłanie zostało ukończone postęp.
- Musisz wiedzieć, kiedy można bezpiecznie odrzucić dane.
Pojedyncze żądanie
Aby przesłać plik w jednej prośbie:
- Utwórz żądanie
POSTna 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 .X-Goog-Upload-Command: ustaw wartośćupload, finalize.
Wyślij prośbę.
Jeśli prośba o przesłanie zostanie przerwana lub otrzymasz 5xx
wykonaj czynności opisane w sekcji Wznawianie
przesyłanie zostało przerwane.
Jeśli żądanie zostanie zrealizowane, otrzymasz stan HTTP 200 OK
i token przesyłania w treści odpowiedzi.
Utwórz ten element multimedialny za pomocą tego tokena przesyłania.
Wiele fragmentów
Aby przesłać plik w kilku fragmentach:
- Utwórz żądanie
POSTna URL sesji, którą można wznowić. -
Dodaj dane fragmentu do treści żądania.
Z wyjątkiem ostatniego fragmentu, który kończy przesyłanie, utwórz i inne w wielu wielokrotnościach akceptowanego rozmiaru. Zachowaj jak największy rozmiar fragmentu, by przesyłanie było skuteczne.
-
Dodaj te nagłówki HTTP:
Content-Length: ustaw liczbę bajtów w bloku.X-Goog-Upload-Command: ustaw naupload. Dla ostatniego fragmentu ustaw wartośćupload, finalize.X-Goog-Upload-Offset: ustaw przesunięcie, przy którym bajtów. Należy przesłać bajty po kolei. Pierwsze przesunięcie to0.
- Wyślij prośbę.
Jeśli prośba o przesłanie zostanie przerwana lub otrzymasz
5xxwykonaj czynności opisane w sekcji Wznawianie przesyłanie zostało przerwane. - Powtórz te czynności dla każdego pozostałego fragmentu w pliku.
Jeśli żądanie się powiedzie, w treści odpowiedzi otrzymasz kod stanu HTTP 200 OK i token przesyłania.
Utwórz
elementu multimedialnego, korzystając z tego tokena przesyłania.
Przykład
Pojedyncze żądanie
Poniższy przykład to żądanie wznowienia przesyłania 3 039 417 bajtów pliku JPEG w jednym żą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 danych:
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 fragmentów
Poniższy przykład to żądanie wznowienia przesyłania
3 039 417 bajtów pliku JPEG podzielonych na fragmenty przy użyciu sesji wznawianej
Adres URL i akceptowany rozmiar fragmentu uzyskany w poprzednim kroku.
W tym przykładzie używany jest fragment o rozmiarze 262 144 bajty,który został zwrócony
pole nagłówka, x-goog-upload-chunk-granularity, gdy
rozpoczęto sesję przesyłania. Pamiętaj, że każdy przesyłany plik zawiera bajty, które
są wielokrotnościami liczby 262 144.
Zainicjuj sesję przesyłania, aby otrzymać adres URL przesyłania i rozmiar fragmentu zgodnie z opisem 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 stan HTTP inny niż 200
wysyła zapytanie do serwera, aby dowiedzieć się, jaka część przesyłania została zakończona pomyślnie.
Oto żądanie POST na URL sesji, którą można wznowić. X-Goog-Upload-Command
powinna 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ć pracę od przesunięcia udostępniane przez serwer, chyba że wyślesz połączone polecenie przesyłania i finalizowania, W takim przypadku możesz wznowić od 0.
Jeśli nagłówek X-Goog-Upload-Status w odpowiedzi HTTP polecenia zapytania
występuje, a wartość nie jest równa active, co oznacza, że w przesyłanym pliku
już usunięte.