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.
Jeśli jesteś deweloperem i korzystasz z bibliotek klienta, pamiętaj, że niektóre z nich zapewniają natywną obsługę przesyłania z możliwością wznawiania;
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ć następujące 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łane dane są
w wielu fragmentach, ze wszystkimi przesłanymi filmami oprócz ostatniego,
musi 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. Przesyłanie pliku
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 ten sposób filmy są przesyłane w wielu żądaniach przez dzielenie danych na fragmenty. Dane są podzielone na fragmenty wielokrotności
x-goog-upload-chunk-granularity
. W razie potrzeby: żądania podzielone na fragmenty można ponowić.Zastosuj tę metodę, 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
POST
na 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
elementu multimedialnego, korzystając z tego tokena przesyłania.
Wiele fragmentów
Aby przesłać plik w kilku fragmentach:
- Utwórz żądanie
POST
na URL sesji, którą można wznowić. -
Dodaj dane fragmentu do treści żądania.
Poza ostatnim fragmentem, 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 fragmentu.X-Goog-Upload-Command
: ustaw wartośćupload
. 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
5xx
wykonaj czynności opisane w sekcji Wznawianie przesyłanie zostało przerwane. - Powtórz powyższe kroki dla każdego pozostałego fragmentu w pliku.
Jeśli żądanie zostanie zrealizowane, otrzymasz stan HTTP 200 OK
i token przesyłania w treści odpowiedzi.
Utwórz
elementu multimedialnego, korzystając z tego tokena przesyłania.
Przykład
Pojedyncze żądanie
Poniższy przykład to żądanie wznowienia przesłania pliku 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 przesłania pliku
3 039 417 bajtów w wielu fragmentach JPEG 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]
Wznawiam przerwane przesyłanie
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ź z serwera zawiera kod stanu HTTP 200 OK
oraz tag
obecnie obowiązujący rozmiar przesyłanych danych.
HTTP/1.1 200 OK X-Goog-Upload-Status: active X-Goog-Upload-Size-Received: 100
Możesz wtedy 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.