Przesyłane multimedia

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:

  1. Część metadanych: Musi występować jako pierwsza, a Content-Type musi odpowiadać jednemu z akceptowanych formatów metadanych.
  2. 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:

  1. Rozpocznij sesję z możliwością wznowienia Wyślij wstępne żądanie do identyfikatora URI przesyłania, który zawiera metadane.
  2. 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.
  3. 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ć:

  1. 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łówek Content-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, ustaw Content-Range na */2000000. Jeśli nie znasz rozmiaru pliku, ustaw Content-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.

  2. 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łówek Range o wartości 0-299999 wskazuje, że odebrane zostało pierwsze 300 000 bajtów pliku.
  3. 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 i 410 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:

  1. Wyślij żądanie do interfejsu API.
  2. Otrzymasz odpowiedź HTTP 503, która wskazuje, że musisz ponownie wysłać żądanie.
  3. Zaczekaj 1 sekundę + losowa liczba_milisekund i spróbuj ponownie.
  4. Otrzymasz odpowiedź HTTP 503, która wskazuje, że musisz ponownie wysłać żądanie.
  5. Zaczekaj 2 sekundy + losowa liczba_milisekund i spróbuj ponownie.
  6. Otrzymasz odpowiedź HTTP 503, która wskazuje, że musisz ponownie wysłać żądanie.
  7. Zaczekaj 4 sekundy i losową liczbę liczb_milisekund i spróbuj ponownie wysłać żądanie.
  8. Otrzymasz odpowiedź HTTP 503, która wskazuje, że musisz ponownie wysłać żądanie.
  9. Zaczekaj 8 sekund + losowa liczba_milisekund i spróbuj ponownie.
  10. Otrzymasz odpowiedź HTTP 503, która wskazuje, że musisz ponownie wysłać żądanie.
  11. Zaczekaj 16 sekund + losowa_liczba_milisekund i spróbuj ponownie.
  12. 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.

Przewodniki po bibliotece klienta API