Interfejs Gmail API umożliwia przesyłanie danych plików podczas tworzenia lub aktualizowania wersji roboczej albo wstawiania lub wysyłania wiadomości.
Opcje przesyłania
Interfejs Gmail API umożliwia przesyłanie określonych typów danych binarnych oraz 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 przesyłanego pliku: maksymalna ilość danych, które można przechowywać w przypadku danej metody.
- Akceptowane typy MIME multimediów: typy danych binarnych, które można przechowywać przy użyciu tej metody.
Prośby o przesłanie możesz przesłać na dowolny z poniższych sposobów. Za pomocą parametru żądania uploadType
określ używaną metodę.
- 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 przenoszenia mniejszych plików i metadanych; przesyła plik wraz z opisującymi go metadanymi, a wszystko to w ramach jednego żądania. - Przesyłanie z możliwością wznowienia:
uploadType=resumable
. Niezawodne przesyłanie, zwłaszcza 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 identyfikatora URI:
Identyfikator URI obiektu /upload dla multimediów. Format punktu końcowego przesyłania to standardowy identyfikator URI zasobu z prefiksem „/upload”. Użyj tego identyfikatora URI, gdy i samodzielnie przenosić dane multimediów.
Przykład:
POST /upload/gmail/v1/users/userId/messages/send
Standardowy identyfikator URI zasobu dla metadanych. Jeśli zasób zawiera jakiekolwiek są pola danych służące do przechowywania metadanych opisujących przesłane . Możesz użyć tego identyfikatora URI przy tworzeniu lub aktualizowaniu wartości metadanych.
Przykład:
POST /gmail/v1/users/userId/messages/send
Proste przesyłanie
Najprostszą metodą przesłania pliku jest przesłanie prostego żądania. Ta opcja jest dobrym rozwiązaniem, gdy:
- Plik jest na tyle mały, aby w razie problemów z połączeniem przesłać go w całości ponownie.
- 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 prośbę o POST
lub PUT
do
identyfikator URI metody /upload i dodaj parametr zapytania
uploadType=media
. Na przykład:
POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?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 częściowego transferu danych.
Przykład: proste przesyłanie
Ten przykład pokazuje, jak wykorzystać proste żądanie przesłania dla Interfejs API Gmaila.
POST /upload/gmail/v1/users/userId/messages/send?uploadType=media HTTP/1.1 Host: www.googleapis.com Content-Type: message/rfc822 Content-Length: number_of_bytes_in_file Authorization: Bearer your_auth_token Email Message 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 {
"id": string,
"threadId": string,
"labelIds": [
string
],
"snippet": string,
"historyId": unsigned long,
"payload": {
"partId": string,
"mimeType": string,
"filename": string,
"headers": [
{
"name": string,
"value": string
}
],
"body": users.messages.attachments Resource,
"parts": [
(MessagePart)
]
},
"sizeEstimate": integer,
"raw": bytes
}
Przesyłanie wieloczęściowe
Jeśli wraz z danymi do przesłania chcesz wysłać metadane, 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 metody /upload i dodaj parametr zapytania
uploadType=multipart
, na przykład:
POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=multipart
Nagłówki HTTP najwyższego poziomu, których należy użyć w przypadku wysyłania wieloczęściowego żądania przesyłania, to między innymi:
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 łą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 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 wymaga dodatkowego nagłówka Content-Type
:
- Część metadanych: musi być na pierwszym miejscu, a pole
Content-Type
musi być zgodne z jednym z akceptowanych formatów metadanych. - Część multimediów: musi być ustawiona jako druga, a wartość
Content-Type
musi być zgodna z jednym z akceptowanych typów MIME multimediów stosowanych w danej metodzie.
Listę akceptowanych typów MIME multimediów i limitów rozmiarów przesyłanych plików znajdziesz w dokumentacji API.
Uwaga: aby utworzyć lub zaktualizować część metadanych
bez przesyłania powiązanych danych, wyślij żądanie POST
lub PUT
do standardowego punktu końcowego zasobu:
https://www.googleapis.com/gmail/v1/users/userId/messages/send
Przykład: przesyłanie wieloczęściowe
Przykład poniżej przedstawia wieloczęściowe żądanie przesłania danych dla interfejsu Gmail API.
POST /upload/gmail/v1/users/userId/messages/send?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 {
"id": string,
"threadId": string,
"labelIds": [
string
],
"snippet": string,
"historyId": unsigned long,
"payload": {
"partId": string,
"mimeType": string,
"filename": string,
"headers": [
{
"name": string,
"value": string
}
],
"body": users.messages.attachments Resource,
"parts": [
(MessagePart)
]
},
"sizeEstimate": integer,
"raw": bytes
} --foo_bar_baz Content-Type: message/rfc822 Email Message data --foo_bar_baz--
Jeśli żądanie zostanie zrealizowane, serwer zwróci kod stanu HTTP 200 OK
i wszystkie metadane:
HTTP/1.1 200 Content-Type: application/json {
"id": string,
"threadId": string,
"labelIds": [
string
],
"snippet": string,
"historyId": unsigned long,
"payload": {
"partId": string,
"mimeType": string,
"filename": string,
"headers": [
{
"name": string,
"value": string
}
],
"body": users.messages.attachments Resource,
"parts": [
(MessagePart)
]
},
"sizeEstimate": integer,
"raw": bytes
}
Przesyłanie z możliwością wznowienia
Aby zwiększyć niezawodność przesyłania plików danych, możesz użyć protokołu przesyłania z możliwością wznawiania. 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 funkcji przesyłania z możliwością wznowienia:
- Rozpocznij sesję, którą można wznowić. Wyślij wstępne żądanie do identyfikatora URI przesyłania zawierającego metadane, jeśli takie istnieją.
- 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.
- Prześlij plik. Wyślij plik multimedialny do identyfikatora URI sesji możliwej do 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 zostało przerwane, sprawdź, ile danych udało się odebrać, i wznów przesyłanie, zaczynając od tego momentu.
Uwaga: identyfikator URI przesyłania wygasa po tygodniu.
Krok 1. Rozpocznij sesję, którą można wznowić
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/gmail/v1/users/userId/messages/send?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 przesyłanych danych, które mają być przeniesione w kolejnych żądaniach. Jeśli długość jest nieznana w momencie wysyłania żądania, możesz pominąć ten nagłówek.- W przypadku dostarczania metadanych:
Content-Type
. Ustaw zgodnie z typem danych metadanych. Content-Length
Ustaw liczbę bajtów podanych w treści tego początkowego żądania. Nie jest wymagane, jeśli używasz kodowania częściowego transferu danych.
Listę akceptowanych typów MIME multimediów i limitów rozmiarów przesyłanych plików znajdziesz w dokumentacji API.
Przykład: żądanie zainicjowania sesji z możliwością wznowienia
Poniższy przykład pokazuje, jak rozpocząć sesję wznawianą dla interfejsu Gmail API.
POST /upload/gmail/v1/users/userId/messages/send?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: message/rfc822 X-Upload-Content-Length: 2000000 {
"id": string,
"threadId": string,
"labelIds": [
string
],
"snippet": string,
"historyId": unsigned long,
"payload": {
"partId": string,
"mimeType": string,
"filename": string,
"headers": [
{
"name": string,
"value": string
}
],
"body": users.messages.attachments Resource,
"parts": [
(MessagePart)
]
},
"sizeEstimate": integer,
"raw": bytes
}
Uwaga: w przypadku początkowego, możliwego do wznowienia żądania aktualizacji bez metadanych pozostaw treść żądania pustą i ustaw nagłówek Content-Length
na 0
.
W następnej sekcji dowiesz się, jak postępować z 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 możliwej do 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ą wznowienia
Oto odpowiedź na żądanie z kroku 1:
HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0
Wartość nagłówka Location
, jak pokazano w przykładowej powyżej odpowiedzi, to identyfikator URI sesji, którego użyjesz jako punktu końcowego HTTP, by przesłać plik lub wysłać zapytanie o stan przesyłania.
Skopiuj i zapisz identyfikator URI sesji, by móc go używać 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. Prośba o przesłanie pliku jest w formacie:
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: żądanie wznowienia przesłania pliku
Oto wznawialna prośba o przesłanie całego pliku wiadomości e-mail o rozmiarze 2 000 000 bajtów dla bieżącego przykładu.
PUT https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1 Content-Length: 2000000 Content-Type: message/rfc822 bytes 0-1999999
Jeśli żądanie zostanie zrealizowane, serwer w odpowiedzi przesyła HTTP 201 Created
wraz z dowolnymi metadanymi powiązanymi z tym zasobem. Jeśli początkowym żądaniem sesji możliwej do wznowienia było PUT
, to żądanie aktualizacji istniejącego zasobu to 200 OK
, wraz z wszelkimi metadanymi powiązanymi z tym zasobem.
Jeśli żądanie przesyłania zostanie przerwane lub otrzymasz z serwera odpowiedź HTTP 503 Service Unavailable
albo inną 5xx
, postępuj zgodnie z procedurą opisaną w artykule Wznawianie przerwanego przesyłania.
Przesyłanie pliku etapami
Dzięki wznawianiu przesyłania możesz podzielić plik na fragmenty i wysłać serię żądań, aby przesłać każdy fragment po kolei. Nie jest to preferowane podejście, ponieważ dodatkowe żądania wiążą się z kosztami wydajności, więc zasadniczo nie jest to potrzebne. Aby jednak zmniejszyć ilość danych przesyłanych w pojedynczym żądaniu, możesz użyć podziału na fragmenty. Jest to przydatne, gdy istnieje stały limit czasowy dla poszczególnych żądań, tak jak w przypadku niektórych klas żądań Google App Engine. W starszych przeglądarkach, które nie mają domyślnie obsługi postępu przesyłania, możesz też wyświetlać wskaźniki postępu przesyłania.
Wznawianie przerwanego przesyłania
Jeśli żądanie przesyłania zostanie zakończone przed otrzymaniem odpowiedzi lub w przypadku otrzymania z serwera odpowiedzi HTTP 503 Service Unavailable
, musisz wznowić przerwane przesyłanie. Aby to zrobić:
- Stan żądania. Sprawdzaj 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łówekContent-Range
wskazujący, że bieżąca pozycja w pliku jest nieznana. Jeśli np. łączna długość pliku wynosi 2 000 000, ustawContent-Range
na*/2000000
. Jeśli nie znasz pełnego rozmiaru pliku, ustawContent-Range
na*/*
.Uwaga: możesz sprawdzać stan poszczególnych fragmentów nie tylko w przypadku przerwania przesyłania. Jest to przydatne na przykład wtedy, gdy chcesz wyświetlać informacje o postępie przesyłania w starszych przeglądarkach.
- Sprawdź liczbę przesłanych bajtów. Przetwórz odpowiedź z zapytania o stan. Serwer używa w odpowiedzi nagłówka
Range
, aby określić, które bajty odebrał do tej pory. Na przykład nagłówekRange
o wartości0-299999
oznacza, że otrzymano pierwsze 300 000 bajtów pliku. - Prześlij pozostałe dane. Wiesz już, gdzie wznowić żądanie, możesz wysłać pozostałe dane lub bieżący fragment. Pamiętaj, że w każdym przypadku pozostałe dane musisz traktować jako oddzielny fragment, więc po wznowieniu przesyłania musisz 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) Pobierz 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. Użyj górnej wartości nagłówka Range
, aby określić, gdzie rozpocząć wznowione przesyłanie.
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 przerwane po przesłaniu wszystkich bajtów, ale przed otrzymaniem odpowiedzi od serwera przez klienta.
3) Wznów 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ło 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
- Jeśli podczas wznawiania lub ponawiania żądań przesyłania wystąpi dowolny błąd serwera
5xx
, użyj strategii wykładniczego ponowienia. Te błędy mogą wystąpić, jeśli serwer jest przeciążony. Wykładniczy czas do ponowienia może pomóc łagodzić tego typu problemy w okresach dużej liczby żądań lub dużego ruchu w sieci. - Inne rodzaje żądań nie powinny być obsługiwane przez wykładniczy czas do ponowienia, ale nadal możesz ponawiać kilka prób. Jeśli chcesz ponawiać te żądania, ogranicz liczbę ponownych 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
i410 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 z powodu dużej liczby żądań lub dużego ruchu sieciowego serwer zwraca błędy, dobrym rozwiązaniem będzie stosowanie wykładniczego czasu do ponowienia. Z drugiej strony nie jest to odpowiednia strategia w przypadku błędów niezwiązanych z ilością sieci czy czasem reakcji, takimi jak nieprawidłowe dane uwierzytelniające autoryzacji lub błędy „Nie znaleziono pliku”.
Prawidłowo używany, rosnący wykładniczy czas ponowienia zwiększa wydajność wykorzystania przepustowości, zmniejsza liczbę żądań wymaganych do uzyskania pomyślnej odpowiedzi i maksymalizuje przepustowość żądań w środowiskach równoczesnych.
Proces implementacji prostego wzrastającego czasu do ponowienia jest następujący:
- Wyślij żądanie do interfejsu API.
- Otrzymasz odpowiedź
HTTP 503
, która oznacza, że należy ponowić żądanie. - Odczekaj 1 sekundę + los_number_milliseconds i spróbuj ponownie.
- Otrzymasz odpowiedź
HTTP 503
, która oznacza, że należy ponowić żądanie. - Odczekaj 2 sekundy + random_number_milliseconds i spróbuj ponownie.
- Otrzymasz odpowiedź
HTTP 503
, która oznacza, że należy ponowić żądanie. - Odczekaj 4 sekundy + random_number_milliseconds i spróbuj ponownie.
- Otrzymasz odpowiedź
HTTP 503
, która oznacza, że należy ponowić żądanie. - Odczekaj 8 sekund + los_number_milliseconds i spróbuj ponownie.
- Otrzymasz odpowiedź
HTTP 503
, która oznacza, że należy ponowić żądanie. - Odczekaj 16 sekund + los_number_milliseconds i spróbuj ponownie.
- Zatrzymaj. Zgłoś lub zapisz błąd.
W tym przykładzie losowo_liczba_milisekund to losowa liczba milisekund mniejsza lub równa 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: oczekiwanie to zawsze (2 ^ n) + losowa_liczba_milisekund, 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 wyłącza się, 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.