Informacje o przesyłaniu multimediów

Interfejs Google Mirror API umożliwia wstawienie załącznika podczas tworzenia nowego elementu osi czasu.

Opcje przesyłania

Interfejs Google Mirror API umożliwia przesyłanie określonych typów danych binarnych lub multimediów. Szczegółowe informacje na temat danych, które możesz przesłać, są określone na stronie referencyjnej dla każdej metody obsługującej przesyłanie multimediów:

  • Maksymalny rozmiar przesyłanego pliku: maksymalna ilość danych, które możesz przechowywać za pomocą tej metody.
  • Akceptowane typy MIME multimediów: typy plików binarnych, które możesz przechowywać za pomocą tej metody.

Prośby o przesłanie treści możesz przesyłać na jeden z tych sposobów. Określ metodę, której używasz z parametrem żądania uploadType.

  • Proste przesyłanie: uploadType=media. Szybkie przesyłanie mniejszych plików, na przykład do 5 MB.
  • Przesyłanie wieloczęściowe: uploadType=multipart. Aby szybko przenieść mniejsze pliki i metadane, wystarczy jedno żądanie, aby przenieść plik wraz z metadanymi, które go opisują.
  • Wznowione przesyłanie: uploadType=resumable. Niezawodny transfer, szczególnie w przypadku większych plików. Ta metoda pozwala wysłać żądanie zainicjowane przez sesję, które może zawierać metadane. Jest to dobra strategia, ponieważ można jej używać w przypadku większości aplikacji, ponieważ działa ona również w przypadku mniejszych plików, których koszt jest wydłużony o 1 dodatkowe żądanie HTTP.

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żyj tego identyfikatora URI podczas przenoszenia danych multimedialnych.

    Przykład: POST /upload/mirror/v1/timeline

  • Standardowy identyfikator URI zasobu używany w metadanych Jeśli zasób zawiera pola danych, to pola te służą do przechowywania metadanych opisujących przesłany plik. Możesz go użyć podczas tworzenia lub aktualizowania wartości metadanych.

    Przykład: POST /mirror/v1/timeline

Proste przesyłanie

Najprostszą metodą przesłania pliku jest przesłanie prostej prośby o przesłanie. Ta opcja jest dobrym rozwiązaniem, gdy:

  • Plik jest wystarczająco mały, aby ponownie przesłać 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 dotyczące tego zasobu w oddzielnym żądaniu lub gdy żadne metadane nie są obsługiwane lub niedostępne.

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

POST https://www.googleapis.com/upload/mirror/v1/timeline?uploadType=media

Nagłówki HTTP, które mają zostać użyte do przesłania prostego żądania przesyłania, to:

  • Content-Type. Ustaw jeden z akceptowanych typów danych przesyłania multimediów określonych w metodzie, które znajdziesz w przewodniku po interfejsie API.
  • Content-Length. Ustaw liczbę bajtów, które przesyłasz. Niewymagane, jeśli używasz kodowania fragmentów.

Przykład: proste przesyłanie

Poniższy przykład pokazuje zastosowanie prostego żądania przesyłania dotyczącego interfejsu Google Mirror API.

POST /upload/mirror/v1/timeline?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 wraz ze wszystkimi metadanymi:

HTTP/1.1 200
Content-Type: application/json

{
  "text": "Hello world!"
}

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 dane są wystarczająco małe, aby je przesłać w całości, jeśli nie uda się nawiązać połączenia.

Aby skorzystać z 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/mirror/v1/timeline?uploadType=multipart

Nagłówki HTTP najwyższego poziomu używane w żądaniu przesyłania wieloczęściowego obejmują:

  • Content-Type. Ustaw wartość „częściowe/powiązane” i dołącz ciąg granicy, którego używasz do identyfikowania 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 ma format treści multipart/related [RFC2387] i składa się z 2 części. Części są określane za pomocą ciągu granicznego, po którym następuje końcowy ciąg granicy po którym pojawiają się 2 łączniki.

Każda część żądania wieloczęściowego wymaga dodatkowego nagłówka Content-Type:

  1. Część metadanych: musi być najwcześniejsza, a Content-Type musi mieć format jednego z akceptowanych formatów.
  2. Część multimedialna: musi być druga, a Content-Type musi odpowiadać jednemu z akceptowanych typów MIME multimediów.

Zapoznaj się z dokumentacją interfejsu API, aby uzyskać listę dozwolonych typów MIME multimediów i limitów rozmiarów przesyłanych plików.

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

Przykład: przesyłanie wieloczęściowe

Przykład poniżej pokazuje żądanie przesłania wieloczęściowego interfejsu Google Mirror API.

POST /upload/mirror/v1/timeline?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

{
  "text": "Hello world!"
}

--foo_bar_baz
Content-Type: image/jpeg

JPEG data
--foo_bar_baz--

Jeśli żądanie zostanie zrealizowane, serwer zwróci kod stanu HTTP 200 OK wraz z metadanymi:

HTTP/1.1 200
Content-Type: application/json

{
  "text": "Hello world!"
}

Przesyłanie możliwe do wznowienia

Aby przesyłać pliki danych w bardziej niezawodny sposób, użyj protokołu wznawiania. Za pomocą tego protokołu możesz wznowić przesyłanie, gdy przesyłanie danych zakończy się niepowodzeniem. Jest to szczególnie przydatne w przypadku przesyłania dużych plików i prawdopodobieństwa przerw w działaniu sieci lub innego błędu transmisji, np. podczas przesyłania z aplikacji klienckiej na urządzenia mobilne. Może też zmniejszyć użycie przepustowości w przypadku awarii sieci, ponieważ nie musisz ponownie przesyłać dużych plików.

Aby przesłać film do wznowienia, wykonaj te czynności:

  1. Rozpoczynanie sesji wznawianej Wyślij wstępne żądanie do identyfikatora URI przesyłania zawierającego metadane (jeśli takie istnieją).
  2. Zapisz identyfikator URI sesji możliwej do wznowienia. Zapisz identyfikator URI sesji zwrócony w odpowiedzi na pierwsze żądanie – będziesz go używać w przypadku pozostałych żądań w tej sesji.
  3. Prześlij plik. Wyślij plik multimedialny do identyfikatora URI możliwej do wznowienia sesji.

Aplikacje, które używają funkcji wznawiania przesyłania, muszą też 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: identyfikator URI przesyłania wygasa po tygodniu.

Krok 1. Rozpocznij sesję wznawiania

Aby zainicjować wznawianie przesyłania, wyślij żądanie POST lub PUT do identyfikatora URI /upload metody i dodaj parametr zapytania uploadType=resumable, na przykład:

POST https://www.googleapis.com/upload/mirror/v1/timeline?uploadType=resumable

Treść tego żądania jest pusta lub zawiera tylko metadane – w kolejnych żądaniach musisz przenieść rzeczywistą zawartość pliku, który chcesz przesłać.

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

  • X-Upload-Content-Type. Ustaw typ MIME danych przesyłania, które mają być przesyłane w kolejnych żądaniach.
  • X-Upload-Content-Length. Ustaw liczbę bajtów danych do przesłania w kolejnych żądaniach. Jeśli w momencie żądania nie można określić długości, możesz pominąć ten nagłówek.
  • Jeśli podajesz metadane: Content-Type. Ustaw zgodnie z typem danych metadanych.
  • Content-Length. Ustaw liczbę bajtów podanych w treści tego wstępnego żądania. Niewymagane, jeśli używasz kodowania fragmentów.

Zapoznaj się z dokumentacją interfejsu API, aby uzyskać listę dozwolonych typów MIME multimediów i limitów rozmiarów przesyłanych plików.

Przykład: żądanie zainicjowania sesji wznowienia

Poniższy przykład pokazuje, jak rozpocząć sesję wznawiania w interfejsie Google Mirror API.

POST /upload/mirror/v1/timeline?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

{
  "text": "Hello world!"
}

Uwaga: w przypadku początkowego żądania wznowienia aktualizacji bez metadanych pozostaw treść żądania i ustaw nagłówek Content-Length na 0.

W następnej sekcji opisujemy, jak postępować z odpowiedziami.

Krok 2. Zapisz identyfikator URI wznawianej sesji

Jeśli żądanie inicjowania sesji się powiedzie, serwer interfejsu API zwróci kod stanu HTTP 200 OK. Zawiera też nagłówek Location, który określa identyfikator URI sesji możliwej do wznowienia. Nagłówek Location (widoczny w poniższym przykładzie) zawiera część parametru zapytania upload_id z unikalnym identyfikatorem przesyłania, który zostanie użyty w tej sesji.

Przykład: odpowiedź na inicjowanie sesji wznowienia

Oto odpowiedź na prośbę z kroku 1:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/mirror/v1/timeline?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

Wartość nagłówka Location (jak w przykładzie powyżej) to identyfikator URI sesji, którego używasz jako punktu końcowego HTTP do przesyłania plików lub wysyłania zapytań o stan przesyłania.

Skopiuj i zapisz identyfikator URI sesji, aby używać go w kolejnych żądaniach.

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 używane podczas tworzenia żądań wznowienia plików zawierają Content-Length. Wpisz w bajtach liczbę bajtów, które przesyłasz w żądaniu. Jest to zwykle rozmiar przesyłanego pliku.

Przykład: wznowienie przesyłania pliku

Oto wznowione żądanie przesłania całego pliku JPEG o rozmiarze 2 000 000 bajtów.

PUT https://www.googleapis.com/upload/mirror/v1/timeline?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 miała stan PUT. W celu zaktualizowania istniejącego zasobu odpowiedź będzie wyglądać tak: 200 OK wraz ze wszystkimi metadanymi powiązanymi z tym zasobem.

Jeśli żądanie przesyłania zostało przerwane lub otrzymasz odpowiedź HTTP 503 Service Unavailable lub inną odpowiedź 5xx z serwera, wykonaj czynności opisane w artykule Wznawianie przerwanego przesyłania.  

Przesyłanie pliku podzielonego fragmentu

Za pomocą wznawianego przesyłania możesz podzielić plik na fragmenty i wysłać serię żądań w celu przesłania każdego pliku w określonej kolejności. Nie jest to preferowana metoda, ponieważ z dodatkowymi żądaniami wiążą się koszty skuteczności i zwykle nie są one potrzebne. Może być jednak konieczne zastosowanie podziału na części, aby zmniejszyć ilość danych przeniesionych w jednym żądaniu. Przydaje się to, gdy istnieje limit czasowy dla poszczególnych żądań, podobnie jak w przypadku niektórych klas żądań Google App Engine. Umożliwia również przesyłanie informacji o postępach w przypadku starszych przeglądarek, które domyślnie nie obsługują tej funkcji.

Wznów przerwane przesyłanie

Jeśli żądanie przesyłania zostanie zakończone przed otrzymaniem odpowiedzi lub otrzymasz odpowiedź HTTP 503 Service Unavailable z serwera, musisz wznowić przesyłanie przerwane. Aby to zrobić:

  1. Stan żądania. Wyślij zapytanie o bieżący stan przesyłania, wysyłając puste żądanie PUT do identyfikatora URI przesyłania. W przypadku tego żądania nagłówki HTTP powinny zawierać nagłówek Content-Range wskazujący nieokreśloną pozycję w pliku. Możesz na przykład ustawić Content-Range na */2000000, jeśli łączna długość pliku to 2 000 000. Jeśli nie znasz rozmiaru pliku, ustaw Content-Range na */*.

    Uwaga: możesz poprosić o stan między fragmentami, a nie tylko w przypadku przerwania przesyłania. Jest to przydatne na przykład wtedy, gdy chcesz wyświetlić wskaźniki postępu przesyłania w przypadku starszych przeglądarek.

  2. Pobierz liczbę bajtów Przetwórz odpowiedź z zapytania o stanie. Serwer używa w nagłówku nagłówka Range, aby określić, które bajtyk otrzymał do tej pory. Na przykład nagłówek Range w kolumnie 0-299999 wskazuje, że otrzymano pierwsze 300 000 bajtów pliku.
  3. Prześlij pozostałe dane. Gdy dowiesz się, gdzie wznowić żądanie, możesz wysłać pozostałe dane lub bieżący fragment. Pozostałe dane musisz traktować jako oddzielne fragmenty, dlatego przy wznowieniu przesyłania musisz przesłać nagłówek Content-Range.
Przykład: wznawianie przesyłania przerwanego

1) Poproś o stan przesyłania.

Żądanie zawiera nagłówek Content-Range,który wskazuje,ż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 dalej do odpowiedzi.

Odpowiedź serwera używa nagłówka Range do wskazania, że otrzymała do tej pory pierwsze 43 bajty pliku. Użyj górnej wartości nagłówka Range, aby określić, gdzie chcesz wznowić przesyłanie.

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

Uwaga: jeśli przesyłanie się zakończyło, odpowiedź może mieć stan 201 Created lub 200 OK. Może się tak zdarzyć, gdy połączenie zostanie przerwane po przesłaniu wszystkich bajtów, ale zanim klient otrzyma odpowiedź z serwera.

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

Za pomocą tego żądania wznowiono przesyłanie, wysyłając pozostałe bajty pliku, począwszy od bajtu.

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 poznać kilka sprawdzonych metod obsługi błędów.

  • Wznów lub spróbuj ponownie przesłać pliki, które się nie powiodły 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 wystąpi błąd 5xx, użyj strategii wykładniczego ponowienia. Te błędy mogą wystąpić, jeśli serwer zostanie przeciążony. Wykładnicze posadzenie może pomóc w uniknięciu tego typu problemów w okresach dużej liczby żądań lub dużego ruchu w sieci.
  • Inne typy żądań nie powinny być obsługiwane przez wzrastające czasy ponowienia, ale część żądań można powtarzać. Ponawiając te żądania, ogranicz liczbę ponownych prób. Twój kod może na przykład nie przekraczać 10 ponownych prób, zanim zgłosi błąd.
  • Obsługuj przesyłanie z możliwością wznawiania przez obsługę błędów 404 Not Found i 410 Gone przez rozpoczęcie przesyłania od początku.

Wykładniczy czas do ponowienia

Wykładniczy czas do ponowienia to standardowa strategia obsługi błędów dla aplikacji sieciowych, w której klient okresowo ponawia próbę nieudanego żądania w coraz dłuższym czasie. Jeśli duża liczba żądań lub duży ruch w sieci powodują zwracanie błędów przez serwer, wykładniczo można spróbować rozwiązać ten problem. Natomiast nie jest to odpowiednie rozwiązanie w przypadku błędów niezwiązanych z ilością czasu sieci lub czasu odpowiedzi, takich jak nieprawidłowe dane uwierzytelniające czy błędy dotyczące nieznalezionych plików.

Prawidłowo używana wykładniczna funkcja zwiększania obciążenia zwiększa wydajność przepustowości, ogranicza liczbę żądań wymaganych do uzyskania skutecznej odpowiedzi i maksymalizuje przepustowość żądań w środowiskach równoczesnych.

Proces implementacji prostego wykładniczego ponawiania wygląda następująco:

  1. Wyślij żądanie do interfejsu API.
  2. Odbierz odpowiedź HTTP 503, która wskazuje, że musisz ponownie wykonać żądanie.
  3. Zaczekaj 1 sekundę i losową liczbę liczb_milisekund i spróbuj ponownie.
  4. Odbierz odpowiedź HTTP 503, która wskazuje, że musisz ponownie wykonać żądanie.
  5. Odczekaj 2 sekundy i losowa_liczba_milisekund i spróbuj ponownie.
  6. Odbierz odpowiedź HTTP 503, która wskazuje, że musisz ponownie wykonać żądanie.
  7. Zaczekaj 4 sekundy i losowa liczba_milisekund i spróbuj ponownie.
  8. Odbierz odpowiedź HTTP 503, która wskazuje, że musisz ponownie wykonać żądanie.
  9. Odczekaj 8 sekund i losowa_liczba_milisekund i spróbuj ponownie.
  10. Odbierz odpowiedź HTTP 503, która wskazuje, że musisz ponownie wykonać żądanie.
  11. Poczekaj 16 sekund + losowa_liczba_milisekund i spróbuj ponownie.
  12. Zatrzymaj. Zgłoś lub zapisz błąd.

W powyższym procesie Los_number_milliseconds oznacza losową liczbę milisekund mniejszą lub równą 1000. Jest to konieczne, ponieważ małe losowe opóźnienie pomaga bardziej równomiernie rozłożyć obciążenie i uniknąć ostemplowania serwera. Wartość liczby losowej_milisekund musi zostać ponownie zdefiniowana po każdym odczekaniu.

Uwaga: czas oczekiwania wynosi zawsze (2 ^ n) + losowa_liczba_milisekund, gdzie n to monotonnie rosnąca liczba całkowita, wstępnie zdefiniowana jako 0. Liczba całkowita n jest zwiększana o 1 na każde wystąpienie (każde żądanie).

Algorytm jest zakończony, gdy liczba n wynosi 5. Ten limit zapobiega ciągłemu ponawianiu próby przez klientów i łączy czas oczekiwania około 32 sekund na uznanie żądania za „nieodwracalny błąd”. Większa liczba ponownych prób jest dozwolona, zwłaszcza jeśli trwa długie przesyłanie. Trzeba jednak pamiętać, że limit czasu ponawiania jest ograniczony do mniej niż minuty.

Przewodniki po bibliotece klienta API