Przesyłane multimedia

Funkcja przesyłania multimediów umożliwia interfejsowi API Campaign Managera 360 przechowywanie danych w chmurze i udostępnianie ich na serwerze. Do przesyłania mogą być przeznaczone zdjęcia, filmy, pliki PDF, pliki ZIP lub inne typy danych.

Przykłady podane w tym dokumencie pokazują wykorzystanie przesyłania multimediów w fikcyjnym interfejsie API Farm. Te same pojęcia dotyczą jednak interfejsu Campaign Managera 360 API.

Opcje przesyłania

Interfejs Campaign Manager 360 API umożliwia przesyłanie określonych typów danych binarnych lub multimediów. Konkretne cechy danych, które możesz przesłać, są określone na stronie referencyjnej w przypadku każdej metody obsługującej przesyłanie multimediów:

  • Maksymalny rozmiar pliku do przesłania: maksymalna ilość danych, które możesz przechowywać za pomocą tej metody.
  • Akceptowane typy MIME multimediów: typy danych binarnych, które można przechowywać przy użyciu tej metody.

Możesz przesyłać pliki na kilka sposobów. Określ metodę, której używasz, za pomocą parametru żądania uploadType.

  • Proste przesyłanie: uploadType=media. Do szybkiego przenoszenia mniejszych plików, np. o wielkości maksymalnie 5 MB.
  • Przesyłanie wieloczęściowe: uploadType=multipart. Do szybkiego przesyłania mniejszych plików i metadanych; przesyła plik wraz z metadanymi, które go opisują, w ramach jednego żądania.
  • Przesyłanie z możliwością wznowienia: uploadType=resumable. niezawodność przesyłania, co jest szczególnie ważne w przypadku większych plików; Ta metoda wykorzystuje żądanie inicjujące sesję, które może opcjonalnie zawierać metadane. To dobra strategia w przypadku większości aplikacji, ponieważ działa też w przypadku mniejszych plików i wymaga dodatkowego żądania HTTP na przesłanie.

Do przesyłania multimediów służy specjalny identyfikator URI. Metody obsługujące przesyłanie multimediów mają 2 punkty końcowe URI:

  • Identyfikator URI /upload dla multimediów. Format punktu końcowego przesyłania to standardowy identyfikator URI zasobu z prefiksem „/upload”. Użyj tego identyfikatora URI podczas przenoszenia samych danych multimedialnych.

    Przykład: POST /upload/farm/v1/animals

  • Standardowy identyfikator URI zasobu dla metadanych. Jeśli zasób zawiera pola danych, są one używane do przechowywania metadanych opisujących przesłany plik. Możesz użyć tego identyfikatora URI przy tworzeniu lub aktualizowaniu wartości metadanych.

    Przykład:POST /farm/v1/animals

Przesyłanie proste

Najprostszą metodą przesłania pliku jest przesłanie prostego żądania. Ta opcja jest dobrym wyborem, jeśli:

  • Plik jest na tyle mały, że można go przesłać ponownie w całości, jeśli połączenie się nie powiedzie.
  • Brak metadanych do wysłania. Może się tak zdarzyć, jeśli zamierzasz wysłać metadane tego zasobu w osobnym żądaniu lub jeśli żadne metadane nie są obsługiwane lub dostępne.

Aby użyć prostego przesyłania, wyślij żądanie POST lub PUT do identyfikatora URI /upload metody i dodaj parametr zapytania uploadType=media. Na przykład:

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=media

Nagłówki HTTP, których należy użyć w prostym żądaniu przesyłania:

  • Content-Type Ustaw jeden z akceptowanych typów przesyłanych danych multimediów do przesyłania, określony w dokumentacji interfejsu API.
  • Content-Length Ustaw liczbę przesyłanych bajtów. Nie jest wymagane, jeśli używasz kodowania transferu w porcjach.

Przykład: proste przesyłanie

Ten przykład pokazuje, jak wykorzystać proste żądanie przesłania dla fikcyjny interfejs Farm API.

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 zostanie zrealizowane, serwer zwróci kod stanu HTTP 200 OK i wszystkie metadane:

HTTP/1.1 200
Content-Type: application/json

{
  "name": "Llama"
}

Przesyłanie wieloczęściowe

Jeśli masz metadane, które chcesz wysłać razem z danymi do przesłania, możesz wysłać pojedyncze żądanie multipart/related. Jest to dobre rozwiązanie, jeśli wysyłane dane są na tyle małe, aby w razie problemów z połączeniem przesłać je w całości w całości.

Aby użyć przesyłania wieloczęściowego, wyślij żądanie POST lub PUT do identyfikatora URI /upload metody 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, których należy używać podczas przesyłania żądania przesyłania wieloczęściowego:

  • Content-Type Ustaw jako wieloczęściową/powiązaną i uwzględnij ciąg granicy, którego używasz do identyfikowania części żądania.
  • Content-Length. Ustaw na łączną liczbę bajtów w ciele żądania. Część multimedialna żądania musi być mniejsza niż maksymalny rozmiar pliku określony dla tej metody.

Treść żądania ma format multipart/related [RFC2387] i zawiera dokładnie 2 części. Części są oznaczone ciągiem znaków granicy, a po nim końcowym – 2 łączniki.

Każda część żądania wieloczęściowego musi zawierać dodatkowy nagłówek Content-Type:

  1. Część metadanych: musi być na pierwszym miejscu, a pole Content-Type musi być zgodne z jednym z akceptowanych formatów metadanych.
  2. Część dotycząca multimediów: musi być drugą częścią, a Content-Type musi pasować do jednego z obsługiwanych przez metodę typów MIME multimediów.

W dokumentacji interfejsu API znajdziesz listę obsługiwanych typów MIME multimediów i limity rozmiarów przesłanych plików dla każdej metody.

Uwaga: aby utworzyć lub zaktualizować tylko część metadanych, bez przesyłania powiązanych danych, wyślij żądanie POST lub PUT do standardowego punktu końcowego zasobu: https://www.googleapis.com/farm/v1/animals

Przykład: przesyłanie w częściach

Przykład poniżej przedstawia żądanie przesyłania wieloczęściowego dla fikcyjnego interfejsu Farm API.

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 zakończy się powodzeniem, serwer zwróci kod stanu HTTP 200 OK wraz z metadanymi:

HTTP/1.1 200
Content-Type: application/json

{
  "name": "Llama"
}

Przesyłanie z możliwością wznowienia

Aby przesyłać pliki danych w bardziej niezawodny sposób, możesz użyć protokołu przesyłania możliwego do wznowienia. Umożliwia on wznowienie operacji przesyłania po tym, jak błąd komunikacji przerwał przepływ danych. Jest to szczególnie przydatne, gdy przesyłasz duże pliki, a prawdopodobieństwo przerwy w działaniu sieci lub innych błędów transmisji jest wysokie, np. gdy przesyłasz z aplikacji klienta mobilnego. Może też zmniejszyć wykorzystanie przepustowości w przypadku awarii sieci, ponieważ nie trzeba ponownie uruchamiać przesyłania dużych plików.

Aby skorzystać z przesyłania możliwego do wznowienia:

  1. Rozpocznij sesję z możliwością wznowienia. Wyślij wstępne żądanie do identyfikatora URI przesyłania zawierającego metadane, jeśli takie istnieją.
  2. Zapisz identyfikator URI sesji, którą można wznawiać. zapisz identyfikator URI sesji zwrócony w odpowiedzi na wstępne żądanie; Użyjesz go w pozostałych żądaniach w tej sesji.
  3. Prześlij plik. Prześlij plik multimedialny do identyfikatora URI sesji z możliwością wznowienia.

Oprócz tego aplikacje korzystające z funkcji wznawiania przesyłania muszą mieć kod umożliwiający wznawianie przerwanego przesyłania. Jeśli przesyłanie zostanie przerwane, sprawdź, ile danych zostało odebranych, a potem wznów przesyłanie od tego miejsca.

Uwaga: identyfikator URI przesyłania wygasa po tygodniu.

Krok 1. Rozpocznij sesję z możliwością wznowienia

Aby rozpocząć przesyłanie, które można wznowić, 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 żądania inicjującego jest pusta lub zawiera tylko metadane. przy kolejnych żądaniach będziesz przenosić zawartość pliku, który chcesz przesłać.

W pierwszym żądaniu HTTP użyj tych nagłówków HTTP:

  • X-Upload-Content-Type Ustaw typ MIME multimediów przesyłanych danych, które mają być przenoszone w kolejnych żądaniach.
  • X-Upload-Content-Length. Ustaw liczbę bajtów danych do przesłania, które mają być przesyłane w kolejnych żądaniach. Jeśli długość jest nieznana w momencie wysyłania żądania, możesz pominąć ten nagłówek.
  • Jeśli przesyłasz metadane: Content-Type. Ustaw zgodnie z typem danych metadanych.
  • Content-Length. Ustaw na liczbę bajtów podanych w ciele tego początkowego żądania. Nie jest wymagane, jeśli używasz kodowania częściowego transferu danych.

W dokumentacji interfejsu API znajdziesz listę obsługiwanych typów MIME multimediów i limity rozmiarów przesłanych plików.

Przykład: żądanie zainicjowania sesji z możliwością wznowienia

Poniższy przykład pokazuje, jak rozpocząć sesję wznawianą dla fikcyjnego interfejsu Farm API.

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 z możliwością wznowienia bez metadanych pozostaw treść żądania pustą, a w nagłówku Content-Length wpisz 0.

W następnej sekcji znajdziesz informacje o tym, jak postępować w przypadku otrzymania takiej odpowiedzi.

Krok 2. Zapisz identyfikator URI sesji do wznawiania

Jeśli żądanie zainicjowania sesji zostanie zrealizowane, serwer interfejsu API w odpowiedzi przesyła kod stanu HTTP 200 OK. Dodatkowo zawiera nagłówek Location, który określa identyfikator URI sesji z możliwością wznowienia. Nagłówek Location widoczny w przykładzie poniżej zawiera część parametru zapytania upload_id, która wskazuje unikalny identyfikator przesyłania, który ma być użyty w tej sesji.

Przykład: odpowiedź na zainicjowanie sesji z możliwością wznawiania

Oto odpowiedź na żądanie z 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 w powyższym przykładzie odpowiedzi, to identyfikator URI sesji, którego użyjesz jako punktu końcowego HTTP do faktycznego przesyłania pliku lub sprawdzania stanu przesyłania.

Skopiuj i zapisz identyfikator URI sesji, aby móc go użyć w kolejnych żądaniach.

Krok 3: prześlij plik

Aby przesłać plik, wyślij żądanie PUT pod identyfikator URI przesyłania uzyskany w poprzednim kroku. Format żądania przesyłania:

PUT session_uri

Nagłówki HTTP używane przy wysyłaniu żądań przesyłania plików z możliwością wznawiania zawierają ciąg Content-Length. Ustaw tę wartość na liczbę bajtów, które chcesz przesłać w ramach tego żądania. Jest to zwykle rozmiar przesyłanego pliku.

Przykład: prośba o przesyłanie plików z możliwością wznowienia procesu

Oto przykładowa prośba o przesłanie całego pliku JPEG o rozmiarach 2 000 000 bajtów, którą można wznowić.

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 w odpowiedzi przesyła HTTP 201 Created wraz ze wszystkimi metadanymi powiązanymi z tym zasobem. Jeśli początkowe żądanie sesji z możliwością wznowienia było PUT, aby zaktualizować istniejący zasób, odpowiedź na powodzenie będzie 200 OK wraz z metadanymi powiązanymi z tym zasobem.

Jeśli żądanie przesyłania zostanie przerwane lub jeśli serwer zwróci odpowiedź HTTP 503 Service Unavailable lub inną odpowiedź 5xx, postępuj zgodnie z instrukcjami opisanymi w artykule Wznowienie przerwanego przesyłania.  

Przesyłanie pliku etapami

Dzięki możliwości wznawiania przesyłania możesz podzielić plik na części i wysłać serię żądań, aby przesyłać każdą część kolejno. Nie jest to preferowane podejście, ponieważ dodatkowe żądania generują koszty, a zazwyczaj nie są potrzebne. Aby jednak ograniczyć ilość danych przesyłanych w jednym żądaniu, może być konieczne użycie dzielenia na fragmenty. Jest to przydatne, gdy w przypadku poszczególnych żądań obowiązuje określony limit czasu, jak ma to miejsce w przypadku niektórych klas żądań Google App Engine. Umożliwia też wyświetlanie informacji o postępie przesyłania w starszych przeglądarkach, które nie obsługują domyślnie postępu przesyłania.

Wznawianie przerwanego przesyłania

Jeśli żądanie przesyłania zostało przerwane przed otrzymaniem odpowiedzi lub jeśli serwer zwróci odpowiedź HTTP 503 Service Unavailable, musisz wznowić przerwane przesyłanie. Aby to zrobić:

  1. Stan prośby. Aby sprawdzić bieżący stan przesyłania, wyślij puste żądanie PUT do identyfikatora URI przesyłania. W przypadku tego żądania nagłówki HTTP powinny zawierać nagłówek Content-Range wskazujący, że bieżąca pozycja w pliku jest nieznana. Jeśli np. łączna długość pliku wynosi 2 000 000, ustaw Content-Range na */2000000. Jeśli nie znasz pełnego rozmiaru pliku, ustaw Content-Range na */*.

    Uwaga: możesz sprawdzać stan poszczególnych fragmentów nie tylko w przypadku przerwania przesyłania. Jest to przydatne, jeśli chcesz wyświetlać informacje o postępie przesyłania w przypadku starszych przeglądarek.

  2. Sprawdź liczbę przesłanych bajtów. Przetworzenie odpowiedzi na zapytanie o stan. Serwer w odpowiedzi używa nagłówka Range, aby określić, które bajty zostały do tej pory odebrane. Na przykład nagłówek Range o wartości 0-299999 oznacza, że otrzymano pierwsze 300 000 bajtów pliku.
  3. Prześlij pozostałe dane. Teraz, gdy już wiesz, gdzie wznowić żądanie, prześlij pozostałe dane lub bieżący fragment. Pamiętaj, że w obu przypadkach pozostałe dane należy traktować jako oddzielny fragment, więc podczas wznawiania przesyłania należy wysłać nagłówek Content-Range.
Przykład: wznawianie przerwanego przesyłania

1) Poproś o stan przesyłania.

To żądanie używa nagłówka Content-Range,aby wskazać,że bieżąca pozycja pliku o wielkości 2 000 000 bajtów jest nieznana.

PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000

2) Wyodrębnij z odpowiedzi liczbę przesłanych do tej pory bajtów.

Odpowiedź serwera wykorzystuje nagłówek Range, aby wskazać, że odebrał do tej pory pierwsze 43 bajty pliku. Aby określić, od którego miejsca wznowić przesyłanie, użyj górnej wartości nagłówka Range.

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: 0-42

Uwaga: po zakończeniu przesyłania odpowiedź dotycząca stanu może mieć wartość 201 Created lub 200 OK. Może się tak zdarzyć, jeśli połączenie zostało zerwane po przesłaniu wszystkich bajtów, ale przed otrzymaniem przez klienta odpowiedzi od serwera.

3) wznowić przesyłanie od miejsca, w którym zostało przerwane.

Kolejne żądanie wznowi przesyłanie, wysyłając pozostałe bajty pliku, zaczynając od bajtu 43.

PUT {session_uri} HTTP/1.1
Content-Length: 1999957
Content-Range: bytes 43-1999999/2000000

bytes 43-1999999

Sprawdzone metody

Podczas przesyłania multimediów warto pamiętać o kilku sprawdzonych metodach dotyczących obsługi błędów.

  • Wznów lub ponów przesyłanie, które nie powiodły się 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
  • Użyj strategii wykładniczego zmniejszania wartości, jeśli podczas wznawiania lub ponownego próbowania żądań przesyłania zwracany jest jakikolwiek błąd serwera 5xx. Te błędy mogą wystąpić, jeśli serwer jest przeciążony. Zmniejszanie skoku wykładniczego może pomóc w rozwiązaniu tego typu problemów w okresach dużego natężenia ruchu w sieci lub dużej liczby żądań.
  • Inne rodzaje żądań nie powinny być obsługiwane przez wykładniczy czas do ponowienia, ale nadal możesz ponawiać kilka prób. Gdy powtarzasz te żądania, ogranicz liczbę prób. Na przykład przed zgłoszeniem błędu kod może zawierać maksymalnie 10 ponownych prób.
  • Podczas wznawiania przesyłania usuń błędy 404 Not Found i 410 Gone, rozpoczynając całe przesyłanie od początku.

Wykładniczy czas do ponowienia

Wykładniczy czas ponowienia to standardowa strategia obsługi błędów w aplikacjach sieciowych, w których klient okresowo ponawia nieudane żądanie w coraz większym czasie. Jeśli duża liczba żądań lub duży ruch w sieci powodują, że serwer zwraca błędy, dobrym sposobem na ich obsługę może być odrzucenie wykładnicze. Nie jest to jednak odpowiednia strategia na radzenie sobie z błędami niezwiązanymi z objętością sieci lub czasem odpowiedzi, np. z błędami nieprawidłowych danych autoryzujących lub nie znaleziono pliku.

Prawidłowo stosowany algorytm sterowania dynamiką zwiększa efektywność wykorzystania przepustowości, zmniejsza liczbę żądań wymaganych do uzyskania odpowiedzi i maksymalizuje przepustowość żądań w środowiskach równoczesnych.

Schemat wdrażania prostego wzrastającego czasu do ponownej próby:

  1. Wyślij żądanie do interfejsu API.
  2. Otrzymasz odpowiedź HTTP 503, która wskazuje, że należy ponownie wysłać żądanie.
  3. Zaczekaj 1 sekundę + random_number_milliseconds i ponów prośbę.
  4. Otrzymasz odpowiedź HTTP 503, która wskazuje, że należy ponownie wysłać żądanie.
  5. Odczekaj 2 sekundy + random_number_milliseconds i spróbuj ponownie.
  6. Otrzymasz odpowiedź HTTP 503, która oznacza, że należy ponowić żądanie.
  7. Odczekaj 4 sekundy + random_number_milliseconds i spróbuj ponownie.
  8. Otrzymasz odpowiedź HTTP 503, która oznacza, że należy ponowić żądanie.
  9. Zaczekaj 8 sekund + random_number_milliseconds i ponownie prześlij żądanie.
  10. Otrzymasz odpowiedź HTTP 503, która oznacza, że należy ponowić żądanie.
  11. Odczekaj 16 sekund + los_number_milliseconds i spróbuj ponownie.
  12. Zatrzymaj. zgłaszać lub rejestrować błędy;

W powyższym procesie parametr random_number_milliseconds jest losową liczbą milisekund mniejszą lub równą 1000. Jest to konieczne, ponieważ wprowadzenie niewielkiego losowego opóźnienia pomaga bardziej równomiernie rozłożyć obciążenie i uniknąć możliwości „przytłoczenia” serwera. Po każdym oczekiwaniu należy ponownie zdefiniować wartość parametru random_number_milliseconds.

Uwaga: czas oczekiwania to zawsze (2 ^ n) + random_number_milliseconds, gdzie n to monotonicznie rosnąca liczba całkowita zdefiniowana początkowo jako 0. Liczba całkowita n zwiększa się o 1 dla każdej iteracji (każdego żądania).

Algorytm jest ustawiony tak, aby zakończyć działanie, gdy n = 5. Taki limit uniemożliwia klientom ponawianie prób w nieskończoność i powoduje, że żądanie zostaje uznane za „błąd nieodwracalny” wynoszący około 32 sekundy. Większa maksymalna liczba ponownych prób to dobre rozwiązanie, zwłaszcza w przypadku długiego przesyłania. pamiętaj, aby ograniczyć opóźnienie ponawiania do rozsądnej, na przykład niecałej minuty.

Przewodniki po bibliotece klienta interfejsu API