Na tej stronie opisujemy, jak za pomocą protokołu REST utworzyć żądanie wznowienia przesyłania do interfejsu Google Photos Library API. Protokół ten umożliwia wznowienie operacji przesyłania, gdy błąd komunikacji przerwie przepływ danych.
Jeśli jesteś programistą korzystającym z bibliotek klienta, pamiętaj, że niektóre biblioteki klienta zapewniają natywną obsługę przesyłania z możliwością wznawiania.
Użyj opcji przesyłania z możliwością wznowienia, jeśli:
- Przesyłasz duże pliki.
- Prawdopodobieństwo przerw w działaniu sieci lub innych problemów z transmisją 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 od początku ponownie uruchamiać dużych plików.
Krok 1. Rozpocznij sesję przesyłania
Zainicjuj sesję wznawiania przesyłania, wysyłając żądanie POST do https://photoslibrary.googleapis.com/v1/uploads. Prześlij plik, korzystając z adresu URL możliwego do wznowienia, który został zwrócony w tym żądaniu.
Żądanie POST musi zawierać następujące nagłówki:
| Pola nagłówka | |
|---|---|
Content-Length |
Ustaw na 0, ponieważ treść żądania jest pusta. |
X-Goog-Upload-Command |
Ustaw jako: start. |
X-Goog-Upload-Content-Type |
Ustaw na typ MIME pliku, np. image/jpeg. |
X-Goog-Upload-Protocol |
Ustaw jako: resumable. |
X-Goog-Upload-Raw-Size |
Ustaw łączną liczbę bajtów danych 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 żądanie się uda, żądanie POST zwróci kod stanu HTTP 200 OK, który zawiera poniższy 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 informacje o wyrównaniu bajtów i wielkością wszystkich fragmentów danych wysyłanych przez klienta. Jeśli przesyłanie odbywa się w kilku częściach, wszystkie z wyjątkiem ostatniego muszą być wielokrotnością tej wartości. Oznacza to, że bajty przesyłanego pliku
muszą być wyrównane 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óry musi zostać użyty do zakończenia przesyłania w przypadku wszystkich pozostałych żądań. Skopiuj i zapisz ten adres URL sesji do wznowienia, aby móc go używać w kolejnych żądaniach.
Krok 3. Przesyłanie pliku
Plik z sesją, którą można wznowić, można przesłać na 2 sposoby:
- W jednej prośbie. Ta metoda zwykle jest najlepsza, ponieważ wymaga mniejszej liczby żądań, a tym samym ma większą wydajność.
-
W kilku częściach. W ramach tej metody przesyłanie danych jest wykonywane w wielu żądaniach poprzez posegmentowanie danych. Dane są podzielone na wielokrotności
x-goog-upload-chunk-granularity. W razie potrzeby można ponowić próbę posegmentowania żądań.Zastosuj tę metodę, jeśli:
- Musisz zmniejszyć ilość danych przenoszonych w jednym żądaniu. Może to być konieczne, gdy istnieje ustalony limit czasu dla poszczególnych żądań.
- Musisz dodać niestandardowy wskaźnik postępu przesyłania.
- Musisz wiedzieć, kiedy można bezpiecznie porzucić dane.
Pojedyncze żądanie
Aby przesłać plik w ramach jednej prośby:
- Utwórz żądanie
POSTna adres URL sesji możliwej do wznowienia. - 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.
Wyślij prośbę.
Jeśli żądanie przesyłania zostanie przerwane lub otrzymasz odpowiedź 5xx, wykonaj czynności opisane w sekcji Wznawianie przerwanego przesyłania.
Jeśli żądanie zostanie zrealizowane, otrzymasz w treści odpowiedzi kod stanu HTTP 200 OK i token przesyłania.
Utwórz element multimedialny za pomocą tego tokena przesyłania.
Kilka fragmentów
Aby przesłać plik w kilku częściach:
- Utwórz żądanie
POSTna adres URL sesji możliwej do wznowienia. -
Dodaj dane fragmentu do treści żądania.
Oprócz ostatniego fragmentu, który kończy przesyłanie, pozostałe fragmenty utwórz wielokrotnością akceptowanego rozmiaru. Aby przesyłanie przebiegało sprawnie, zadbaj o to, by fragment był jak największy.
-
Dodaj te nagłówki HTTP:
Content-Length: ustaw liczbę bajtów we fragmencie.X-Goog-Upload-Command: ustaw naupload. Dla ostatniego fragmentu ustaw wartośćupload, finalize.X-Goog-Upload-Offset: ustaw przesunięcie, z którym mają być zapisywane bajty. Pamiętaj, że bajty należy przesłać szeregowo. Pierwsze przesunięcie wynosi0.
- Wyślij prośbę.
Jeśli żądanie przesyłania zostanie przerwane lub otrzymasz odpowiedź
5xx, wykonaj czynności opisane w sekcji Wznawianie przerwanego przesyłania. - Powtórz powyższe kroki w przypadku każdego pozostałego fragmentu pliku.
Jeśli żądanie zostanie zrealizowane, otrzymasz w treści odpowiedzi kod stanu HTTP 200 OK i token przesyłania.
Utwórz element multimedialny za pomocą tego tokena przesyłania.
Przykład
Pojedyncze żądanie
Poniższy przykład przedstawia żądanie wznowienia przesyłania pliku JPEG o wielkości 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]
Kilka fragmentów
Poniższy przykład przedstawia możliwą do wznowienia żądanie przesłania 3 039 417 bajtów pliku JPEG w kilku fragmentach z użyciem adresu URL sesji możliwego do wznowienia i akceptowanej szczegółowości dotyczącej rozmiaru fragmentu uzyskanej w poprzednim kroku.
W tym przykładzie użyto fragmentu o wielkości 262 144 bajtów, który został zwrócony w polu nagłówka (x-goog-upload-chunk-granularity) po zainicjowaniu sesji przesyłania. Pamiętaj, że każdy przesyłany plik zawiera bajty, które są wielokrotnością 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]
Wznawianie przerwanego przesyłania
Jeśli żądanie przesyłania zostanie przerwane lub otrzymasz kod stanu HTTP inny niż 200, wyślij zapytanie do serwera, aby sprawdzić, w jakim stopniu pliki zostały przesłane.
Oto żądanie POST na adres URL sesji możliwej do wznowienia. Pole X-Goog-Upload-Command powinno 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ź z 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
Wtedy będzie można wznowić przesyłanie. Musisz wznowić działanie po osiągnięciu przesunięcia podanego przez serwer, chyba że wyślesz połączone polecenie przesyłania i finalizacji. W takim przypadku możesz też wznowić działanie od przesunięcia 0.
Jeśli nagłówek X-Goog-Upload-Status w odpowiedzi HTTP polecenia zapytania jest obecny, a wartość nie wynosi active, oznacza to, że przesyłanie zostało już zakończone.