Funkcja przesyłania multimediów pozwala interfejsowi Campaign Manager 360 API przechowywać dane w chmurze i udostępniać je serwerowi. Do rodzajów danych, które można przesłać, należą zdjęcia, filmy, pliki PDF, pliki ZIP lub dowolne inne typy danych.
Przykłady w tym dokumencie pokazują, że w fikcyjnym interfejsie Farm API wykorzystywany jest przesyłanie multimediów. Te same koncepcje odnoszą się jednak do interfejsu API Campaign Managera 360.
Opcje przesyłania
Interfejs Campaign Manager 360 API umożliwia przesyłanie określonych typów danych binarnych lub multimediów. Konkretne dane do przesłania można określić na stronie referencyjnej w przypadku każdej metody, która obsługuje przesyłanie multimediów:
- Maksymalny rozmiar przesyłanego pliku: maksymalna ilość danych, jaką można przesłać przy użyciu tej metody.
- Akceptowane typy MIME multimediów: rodzaje danych binarnych, które możesz przechowywać przy użyciu tej metody.
Żądania przesyłania możesz przesłać na jeden z tych sposobów. Podaj metodę, której używasz w parametrze żądania uploadType
.
- Proste przesyłanie:
uploadType=media
. Aby szybko przesyłać mniejsze pliki, na przykład 5 MB lub mniej. - Przesyłanie wieloczęściowe:
uploadType=multipart
. Szybkie przenoszenie mniejszych plików i metadanych. Jednorazowo przenosi plik wraz z metadanymi, które go opisują. - Wznowienie przesyłania:
uploadType=resumable
. Zapewnia to niezawodny transfer, szczególnie w przypadku większych plików. Ta metoda pozwala wysyłać żądania inicjujące sesję, ale mogą też zawierać metadane. Jest to dobry wybór w przypadku większości aplikacji, ponieważ działa on w przypadku mniejszych plików, które kosztują jedno dodatkowe żądanie HTTP przy każdym przesłaniu.
Podczas przesyłania multimediów używasz specjalnego identyfikatora URI. Metody obsługujące przesyłanie multimediów mają 2 punkty końcowe URI:
Identyfikator URI /upload dla multimediów. Punkt końcowy przesyłania to standardowy identyfikator URI zasobu z prefiksem „/upload”. Używaj tego identyfikatora URI podczas przenoszenia danych multimedialnych.
Przykład:
POST /upload/farm/v1/animals
Standardowy identyfikator URI zasobu dla metadanych Jeśli zasób zawiera pola danych, służą one do przechowywania metadanych opisujących przesłany plik. Możesz użyć tego identyfikatora URI podczas tworzenia lub aktualizowania wartości metadanych.
Przykład:
POST /farm/v1/animals
Proste przesyłanie
Najprostszą metodą przesyłania plików jest przesyłanie próśb o ich przesłanie. Ta opcja przydaje się, gdy:
- Plik jest na tyle mały, że nie można przesłać go w całości, jeśli nie uda się nawiązać połączenia.
- Brak metadanych do wysłania. Może się tak zdarzyć, jeśli zamierzasz wysyłać metadane dla tego zasobu w osobnym żądaniu lub gdy żadne metadane nie są obsługiwane lub dostępne.
Aby użyć prostego przesyłania, wyślij żądanie POST
lub PUT
do identyfikatora URI metody /upload i dodaj parametr zapytania uploadType=media
. Na przykład:
POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=media
Nagłówki HTTP, które mają być użyte podczas tworzenia prostego żądania przesyłania, obejmują:
Content-Type
. Ustaw jeden z akceptowanych typów danych przesyłania multimediów wymienionych w dokumentacji.Content-Length
. Ustaw liczbę bajtów do przesłania. Nie jest to wymagane, jeśli używasz kodowania transferu cząstkowego.
Przykład: proste przesyłanie
Poniższy przykład pokazuje zastosowanie prostego żądania przesyłania w przypadku fikcyjnego interfejsu API Farm.
POST /upload/farm/v1/animals?uploadType=media HTTP/1.1 Host: www.googleapis.com Content-Type: image/jpeg Content-Length: number_of_bytes_in_file Authorization: Bearer your_auth_token JPEG data
Jeśli żądanie się powiedzie, serwer zwraca kod stanu HTTP 200 OK
wraz z metadanymi:
HTTP/1.1 200 Content-Type: application/json { "name": "Llama" }
Przesyłanie wieloczęściowe
Jeśli masz metadane, które chcesz przesłać wraz z danymi do przesłania, możesz wysłać jedno żądanie multipart/related
. Jest to dobry wybór, jeśli wysyłane dane są wystarczająco małe, aby ponownie przesłać całość, jeśli połączenie nie powiedzie się.
Aby użyć przesyłania wieloczęściowego, wyślij żądanie POST
lub PUT
do identyfikatora URI metody /upload i dodaj parametr zapytania uploadType=multipart
, na przykład:
POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=multipart
Nagłówki HTTP najwyższego poziomu używane w żądaniu przesyłania wieloczęściowego obejmują:
Content-Type
. Wybierz wieloczęściową/powiązaną wartość i dodaj ciąg graniczny, którego używasz do wskazywania części żądania.Content-Length
. Ustaw łączną liczbę bajtów w treści żądania. Część multimedialna żądania musi być mniejsza niż maksymalny rozmiar pliku określony dla tej metody.
Treść żądania jest sformatowana jako typ treści multipart/related
[RFC2387] i zawiera dokładnie 2 części. Części są określane za pomocą ciągu granicznego, a po ostatnim końcu granicy występują dwa łączniki.
Każda część żądania wieloczęściowego wymaga dodatkowego nagłówka Content-Type
:
- Część metadanych: Musi występować jako pierwsza, a
Content-Type
musi odpowiadać jednemu z akceptowanych formatów metadanych. - Część multimediów: musi być podana w drugiej kolejności, a
Content-Type
musi być zgodna z jednym z obsługiwanych typów MIME multimediów.
W dokumentacji interfejsu API znajdziesz listę akceptowanych typów i formatów MIME multimediów dla przesyłanych plików.
Uwaga: aby utworzyć lub zaktualizować tylko część metadanych, bez przesyłania powiązanych danych wystarczy wysłać żądanie POST
lub PUT
do standardowego punktu końcowego zasobów: https://www.googleapis.com/farm/v1/animals
Przykład: przesyłanie wieloczęściowe
Przykład poniżej pokazuje żądanie przesłania wieloczęściowego żądania do fikcyjnego interfejsu API Farm.
POST /upload/farm/v1/animals?uploadType=multipart HTTP/1.1 Host: www.googleapis.com Authorization: Bearer your_auth_token Content-Type: multipart/related; boundary=foo_bar_baz Content-Length: number_of_bytes_in_entire_request_body --foo_bar_baz Content-Type: application/json; charset=UTF-8 { "name": "Llama" } --foo_bar_baz Content-Type: image/jpeg JPEG data --foo_bar_baz--
Jeśli żądanie się powiedzie, serwer zwróci kod stanu HTTP 200 OK
wraz z metadanymi:
HTTP/1.1 200 Content-Type: application/json { "name": "Llama" }
Przesyłanie możliwe do wznowienia
Aby przesyłać pliki danych w sposób bardziej niezawodny, możesz użyć protokołu przesyłania możliwego do wznowienia. Protokół ten umożliwia wznowienie przesyłania po przerwaniu komunikacji przez błąd. Jest to szczególnie przydatne w przypadku przesyłania dużych plików, gdy istnieje ryzyko, że podczas przerwy w działaniu sieci lub wystąpi inny błąd transmisji, np. podczas przesyłania danych z aplikacji mobilnej klienta. Może również zmniejszyć wykorzystanie przepustowości w przypadku awarii sieci, ponieważ nie musisz ponownie przesyłać dużych plików.
Aby zacząć przesyłać dane ze wznowienia, należy wykonać te czynności:
- Rozpocznij sesję z możliwością wznowienia Wyślij wstępne żądanie do identyfikatora URI przesyłania, który zawiera metadane.
- Zapisz identyfikator URI wznawianej sesji. Zapisz identyfikator URI sesji zwrócony w odpowiedzi na pierwsze żądanie. Będzie on potrzebny w pozostałych żądaniach w tej sesji.
- Prześlij plik. Wyślij plik multimedialny do identyfikatora URI wznawianej sesji.
Aplikacje, które korzystają z wznawiania przesyłania, muszą dodatkowo mieć kod umożliwiający wznowienie przesyłania. Jeśli przesyłanie zostanie przerwane, sprawdź, ile danych zostało odebranych, a następnie rozpocznij przesyłanie od tego momentu.
Uwaga: przesyłany identyfikator URI wygasa po tygodniu.
Krok 1. Rozpocznij sesję wznowioną
Aby rozpocząć przesyłanie wznowione, wyślij żądanie POST
lub PUT
do identyfikatora URI metody /upload i dodaj parametr zapytania uploadType=resumable
, na przykład:
POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable
Treść tego inicjowania jest pusta lub zawiera tylko metadane – w kolejnych żądaniach przenosisz zawartość pliku, który chcesz przesłać.
Na początku tego żądania używaj tych nagłówków HTTP:X-Upload-Content-Type
. Ustaw typ MIME multimediów na dane przesyłania, które będą przesyłane w kolejnych żądaniach.X-Upload-Content-Length
. Ustaw liczbę bajtów danych do przesłania w kolejnych żądaniach. Jeśli długość żądania jest nieznana w czasie żądania, możesz pominąć ten nagłówek.- Jeśli podajesz metadane:
Content-Type
. Ustaw typ zgodnie z typem danych metadanych. Content-Length
. Ustaw liczbę bajtów podanych w treści tego wstępnego żądania. Nie jest to wymagane, jeśli używasz kodowania transferu cząstkowego.
W dokumentacji interfejsu API znajdziesz listę akceptowanych typów i formatów MIME multimediów dla przesyłanych plików.
Przykład: żądanie zainicjowania sesji do wznowienia
Poniższy przykład pokazuje, jak rozpocząć sesję wznawiania dla fikcyjnego interfejsu API Farm.
POST /upload/farm/v1/animals?uploadType=resumable HTTP/1.1 Host: www.googleapis.com Authorization: Bearer your_auth_token Content-Length: 38 Content-Type: application/json; charset=UTF-8 X-Upload-Content-Type: image/jpeg X-Upload-Content-Length: 2000000 { "name": "Llama" }
Uwaga: w przypadku początkowego żądania aktualizacji bez możliwości wznowienia bez metadanych pozostaw treść żądania pustą i ustaw nagłówek Content-Length
na 0
.
W następnej sekcji dowiesz się, jak postępować w odpowiedzi.
Krok 2. Zapisz identyfikator URI sesji wznawianej
Jeśli żądanie zainicjowania sesji się powiedzie, serwer interfejsu API wyśle kod stanu HTTP 200 OK
. Zawiera też nagłówek Location
, który określa identyfikator URI wznawianej sesji. Nagłówek Location
widoczny w poniższym przykładzie zawiera część parametru zapytania upload_id
, która nadaje unikalny identyfikator przesyłania na potrzeby tej sesji.
Przykład: odpowiedź na zainicjowanie sesji
Oto odpowiedź na to żądanie w kroku 1:
HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0
Wartość nagłówka Location
(jak pokazano powyżej w przykładowej odpowiedzi) to identyfikator URI sesji, który będzie używany jako punkt końcowy HTTP do wykonywania przesłanego pliku lub wysyłania informacji o stanie przesyłania.
Skopiuj i zapisz identyfikator URI sesji, aby móc go używać w przyszłości.
Krok 3: prześlij plik
Aby przesłać plik, wyślij żądanie PUT
na identyfikator URI przesyłania uzyskany w poprzednim kroku. Format żądania przesłania:
PUT session_uri
Nagłówki HTTP, które mają być używane podczas wysyłania żądań wznawiania plików, obejmują Content-Length
. Ustaw liczbę bajtów przesyłanych w tym żądaniu, czyli zwykle rozmiar przesyłanego pliku.
Przykład: żądanie przesłania pliku do wznowienia
Oto wznowione żądanie przesłania całego pliku JPEG o rozmiarze 2 000 000 bajtów.
PUT https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1 Content-Length: 2000000 Content-Type: image/jpeg bytes 0-1999999
Jeśli żądanie zostanie zrealizowane, serwer wyśle odpowiedź HTTP 201 Created
z metadanymi powiązanymi z tym zasobem. Początkowa prośba o wznowienie sesji dotyczyła PUT
, aby zaktualizować istniejący zasób. Odpowiedź otrzymana w odpowiedzi otrzyma 200 OK
, wraz ze wszystkimi metadanymi powiązanymi z tym zasobem.
Jeśli żądanie przesyłania zostało przerwane lub jeśli HTTP 503 Service Unavailable
albo inna odpowiedź 5xx
została przesłana z serwera, postępuj zgodnie z procedurą opisaną w sekcji Wznawianie przerwanego przesyłania.
Przesyłanie pliku fragmentami
Dzięki wznawianiu przesyłania możesz podzielić plik na fragmenty i wysyłać kolejne żądania po kolei. Nie jest to zalecane rozwiązanie, ponieważ dodatkowe koszty są powiązane z dodatkowymi żądaniami i zasadniczo nie są potrzebne. Może być jednak konieczne zastosowanie podziału na fragmenty, aby zmniejszyć ilość danych przesyłanych w jednym żądaniu. Jest to przydatne, gdy obowiązuje limit czasowy dla poszczególnych żądań, jak w przypadku niektórych klas żądań Google App Engine. Umożliwia również wyświetlanie wskazówek dotyczących postępu przesyłania w starszych przeglądarkach, które domyślnie nie obsługują postępu przesyłania.
Wznawianie przerwanego przesyłania
Jeśli przesyłanie zostanie zakończone przed otrzymaniem odpowiedzi lub jeśli otrzymasz odpowiedź HTTP 503 Service Unavailable
z serwera, musisz wznowić przesyłanie. Aby to zrobić:
- Stan prośby. Wyślij zapytanie o bieżący stan przesyłania, wysyłając puste żądanie
PUT
do identyfikatora URI przesyłania. W tym żądaniu nagłówki HTTP powinny zawierać nagłówekContent-Range
wskazujący, że bieżąca pozycja w pliku jest nieznana. Jeśli na przykład łączna długość pliku wynosi 2 000 000 plików, ustawContent-Range
na*/2000000
. Jeśli nie znasz rozmiaru pliku, ustawContent-Range
na*/*
.Uwaga: możesz poprosić o stan między fragmentami, a nie tylko po przerwaniu przesyłania. Jest to przydatne na przykład wtedy, gdy chcesz wyświetlić wskaźniki postępu przesyłania dla starszych przeglądarek.
- Pobierz liczbę bajtów. Przetwórz odpowiedź z zapytania o stan. Serwer używa nagłówka
Range
w odpowiedzi, aby określić, ile bajtów otrzymało do tej pory. Na przykład nagłówekRange
o wartości0-299999
wskazuje, że odebrane zostało pierwsze 300 000 bajtów pliku. - Prześlij pozostałe dane. Gdy wiesz już, gdzie chcesz wysłać żądanie, możesz wysłać pozostałe dane lub bieżący fragment. Pamiętaj, że pozostałe dane musisz traktować jako oddzielny fragment, więc wznawiając przesyłanie, musisz wysłać nagłówek
Content-Range
.
Przykład: wznawianie przesyłania
1) Poproś o stan przesyłania.
To żądanie używa nagłówka Content-Range
do wskazania, że bieżąca pozycja w pliku 2 000 000 bajtów jest nieznana.
PUT {session_uri} HTTP/1.1 Content-Length: 0 Content-Range: bytes */2000000
2) Wyodrębnij liczbę bajtów przesłanych do odpowiedzi.
Odpowiedź serwera wykorzystuje nagłówek Range
, aby wskazać, że otrzymała pierwsze 43 bajty pliku. Użyj górnej wartości nagłówka Range
, aby określić, gdzie chcesz rozpocząć wznowienie przesyłania.
HTTP/1.1 308 Resume Incomplete Content-Length: 0 Range: 0-42
Uwaga: w przypadku zakończonego przesyłania odpowiedź może mieć stan 201 Created
lub 200 OK
. Może się tak zdarzyć, jeśli połączenie zostało przerwane po przesłaniu wszystkich bajtów, ale przed otrzymaniem odpowiedzi od serwera.
3) Wznów przesyłanie od miejsca, w którym zostało przerwane.
To żądanie wznawia przesyłanie, wysyłając pozostałe bajty pliku, począwszy od bajtu 43.
PUT {session_uri} HTTP/1.1 Content-Length: 1999957 Content-Range: bytes 43-1999999/2000000 bytes 43-1999999
Sprawdzone metody
Przy przesyłaniu multimediów warto poznać kilka sprawdzonych metod obsługi błędów.
- Wznawianie lub ponawianie prób zakończonych niepowodzeniem z powodu przerw w połączeniu lub błędów
5xx
, w tym:500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
- Jeśli podczas wznawiania lub ponawiania żądań przesyłania zwracany jest błąd serwera
5xx
, użyj strategii wykładniczego ponowienia. Te błędy mogą wystąpić, gdy serwer jest przeciążony. Wykładnicze ponowienie może pomóc uniknąć tego typu problemów podczas zwiększonej liczby żądań lub dużego ruchu sieciowego. - Inne typy żądań nie powinny być obsługiwane przez wykładnicze ponowienie, ale wciąż możesz próbować wiele z nich. Ponawiając liczbę żądań, ogranicz liczbę ponownych prób. Na przykład kod błędu może ograniczyć się do 10 ponownych prób.
- Napraw błędy
404 Not Found
i410 Gone
w przypadku wznawiania przesyłania, zaczynając przesyłanie od początku.
Wykładnicze ponowienie
Wykładnicze ponowienie to standardowa strategia obsługi błędów stosowana w aplikacjach sieciowych, w której klient okresowo próbuje ponownie zrealizować nieudane żądanie przez dłuższy czas. Jeśli duża liczba żądań lub duży ruch sieciowy powoduje zwrócenie błędów na serwerze, wykładniczo może zostać użyta ta metoda. Analogicznie nie nadaje się do radzenia sobie z błędami, które nie są związane z wolnością sieci lub czasem odpowiedzi, na przykład nieprawidłowymi danymi uwierzytelniającymi lub błędami dotyczącymi nieznalezionych plików.
Prawidłowo używany wykładniczy czas do ponowienia zwiększa wydajność wykorzystania przepustowości, ogranicza liczbę żądań wymaganych do otrzymania odpowiedzi zakończonej powodzeniem oraz maksymalizuje przepustowość żądań w środowiskach równoczesnych.
Proces wdrażania prostego wykładniczego ponowienia wygląda tak:
- Wyślij żądanie do interfejsu API.
- Otrzymasz odpowiedź
HTTP 503
, która wskazuje, że musisz ponownie wysłać żądanie. - Zaczekaj 1 sekundę + losowa liczba_milisekund i spróbuj ponownie.
- Otrzymasz odpowiedź
HTTP 503
, która wskazuje, że musisz ponownie wysłać żądanie. - Zaczekaj 2 sekundy + losowa liczba_milisekund i spróbuj ponownie.
- Otrzymasz odpowiedź
HTTP 503
, która wskazuje, że musisz ponownie wysłać żądanie. - Zaczekaj 4 sekundy i losową liczbę liczb_milisekund i spróbuj ponownie wysłać żądanie.
- Otrzymasz odpowiedź
HTTP 503
, która wskazuje, że musisz ponownie wysłać żądanie. - Zaczekaj 8 sekund + losowa liczba_milisekund i spróbuj ponownie.
- Otrzymasz odpowiedź
HTTP 503
, która wskazuje, że musisz ponownie wysłać żądanie. - Zaczekaj 16 sekund + losowa_liczba_milisekund i spróbuj ponownie.
- Zatrzymaj. Zgłoś lub zarejestruj błąd.
W powyższym przepływie losowa liczba_milisekund to losowa liczba milisekund mniejsza lub równa 1000. Jest to konieczne, ponieważ małe, losowe opóźnienie pomaga bardziej równomiernie rozłożyć obciążenie i uniknąć ostemplowania serwera. Wartość losowej liczby_milisekund musi być zmieniana po każdym odczekaniu.
Uwaga: czas oczekiwania wynosi zawsze (2 ^ n) + losowa_liczba_milisekund, gdzie n to monotonicznie rosnąca liczba całkowita, wstępnie zdefiniowana jako 0. Liczba całkowita n zwiększa się o 1 w przypadku każdego iteracji (dla każdego żądania).
Algorytm ma się zakończyć, gdy n ma wartość 5. Ten limit nie pozwala klientowi na ponawianie próby bezterminowo. Spowoduje to około 32-sekundowe opóźnienie, zanim żądanie zostanie uznane za „nieodwracalny błąd”. Dopuszczalna jest ponowna liczba ponownych prób, zwłaszcza jeśli trwa przesyłanie długiego materiału. Pamiętaj, aby ustawić limit ponawiania próby w rozsądnym czasie, na przykład krótszym niż minuta.