Konkretnym podejściem do wsadowego grupowania danych jest globalny punkt końcowy HTTP HTTP Batch (www.googleapis.com/batch), który został wyłączony 12 sierpnia 2020 r., jak zapowiadaliśmy na blogu Google Developers. Inne metody grupowania wciąż działają, jak opisano na pozostałej stronie. Jeśli Twój kod używa globalnego punktu końcowego wsadowego protokołu HTTP, przeczytaj posta na blogu, aby dowiedzieć się, jak przejść na inne metody, takie jak punkty końcowe HTTP wsadowego interfejsu API (www.googleapis.com/batch/API/VERSION).
Ten dokument pokazuje, jak łączyć wywołania interfejsu API, aby zmniejszyć liczbę połączeń HTTP, które musi nawiązać klient.
Ten dokument dotyczy wysyłania żądań zbiorczych za pomocą żądania HTTP. Jeśli zamiast tego do przesyłania żądań zbiorczych używasz biblioteki klienta Google, zapoznaj się z dokumentacją biblioteki klienta.
Omówienie
Każde połączenie HTTP, które generuje klient, wiąże się z pewnym nakładem pracy. Interfejs Google Mirror API obsługuje wsadowe, dzięki czemu klient może umieścić kilka wywołań interfejsu API w jednym żądaniu HTTP.
Przykłady sytuacji, w których może być przydatna funkcja grupowania:
- Dopiero zaczynasz korzystać z interfejsu API i masz dużo danych do przesłania.
- Użytkownik wprowadził zmiany w danych, gdy aplikacja była offline (bez połączenia z internetem), więc musi ona synchronizować dane lokalne z serwerem poprzez wysyłanie wielu aktualizacji i usuwania.
W każdym przypadku zamiast wysyłać każde wywołanie oddzielnie, możesz połączyć je w jedno żądanie HTTP. Wszystkie żądania wewnętrzne muszą być kierowane do tego samego interfejsu API Google.
W jednym żądaniu zbiorczym możesz utworzyć maksymalnie 1000 połączeń. Jeśli chcesz wykonać więcej połączeń, użyj kilku żądań zbiorczych.
Uwaga: system wsadowy interfejsu Google Mirror API korzysta z tej samej składni co system zbiorczego przetwarzania danych O, ale jego semantyka jest inna.
Szczegóły wsadu
Żądanie zbiorcze składa się z wielu wywołań interfejsu API połączonych w jedno żądanie HTTP, które można wysłać do batchPath określonego w dokumentacji interfejsu API wykrywania. Domyślna ścieżka to /batch/api_name/api_version. Ta sekcja szczegółowo opisuje składnię grupy. Później znajdziesz przykład.
Uwaga: zestaw n żądań zbiorczych wlicza się do limitu wykorzystania jako n żądań, a nie jako jedno żądanie. Żądanie zbiorcze jest przed przetwarzaniem rozdzielane na zestaw żądań.
Format żądania zbiorczego
Żądanie zbiorcze to pojedyncze standardowe żądanie HTTP zawierające wiele wywołań interfejsu Google Mirror API korzystającego z typu treści multipart/mixed. W tym głównym żądaniu HTTP każda część zawiera zagnieżdżone żądanie HTTP.
Każda część zaczyna się od własnego nagłówka HTTP Content-Type: application/http. Może też mieć opcjonalny nagłówek Content-ID. Jednak nagłówki są tylko po to, aby zaznaczyć początek części, ponieważ są niepowiązane z żądaniem zagnieżdżonym. Po wyodrębnieniu przez serwer żądania wsadowego w osobne żądania nagłówki części są ignorowane.
Treść każdej części jest kompletnym żądaniem HTTP z własnym czasownikiem, adresem URL, nagłówkami i treścią. Żądanie HTTP może zawierać tylko część adresu URL. W żądaniach zbiorczych nie można używać pełnych adresów URL.
Nagłówki HTTP zewnętrznego żądania zbiorczego, z wyjątkiem nagłówków Content-, takich jak Content-Type, mają zastosowanie do każdego żądania w grupie. Jeśli podasz nagłówek nagłówka HTTP zarówno w żądaniu zewnętrznym, jak i pojedynczym wywołaniu, wartość tego nagłówka zastępuje wartość nagłówka żądania zbiorczego. Nagłówki pojedynczego połączenia dotyczą tylko tego połączenia.
Jeśli na przykład podasz nagłówek autoryzacji konkretnego wywołania, zostanie on zastosowany tylko do tego wywołania. Jeśli podasz nagłówek autoryzacji w żądaniu zewnętrznym, będzie on stosowany do wszystkich wywołań, chyba że zastąpi on własny nagłówek.
Gdy serwer odbiera żądanie zbiorcze, stosuje parametry i nagłówek zewnętrznego żądania do każdej części, a następnie traktuje każdą część jak osobne żądanie HTTP.
Odpowiedź na żądanie zbiorcze
Odpowiedź serwera to pojedyncza standardowa odpowiedź HTTP z typem treści multipart/mixed. Każda część to odpowiedź na jedno z żądań w żądaniu zbiorczym, w takiej samej kolejności jak żądania.
Podobnie jak w częściach żądania, każda część odpowiedzi zawiera pełną odpowiedź HTTP razem z kodem stanu, nagłówkami i treścią. Podobnie jak w części żądania, każda część odpowiedzi jest poprzedzona nagłówkiem Content-Type oznaczającym początek części.
Jeśli dana część żądania ma nagłówek Content-ID, to odpowiednia część odpowiedzi ma pasujący nagłówek Content-ID, przy czym pierwotna wartość jest poprzedzona ciągiem response-, jak widać w tym przykładzie.
Uwaga: serwer może wykonywać wywołania w dowolnej kolejności. Nie licz na ich realizację w kolejności, w jakiej zostały przez Ciebie określone. Jeśli chcesz mieć pewność, że dwa wywołania występują w określonej kolejności, nie możesz wysłać ich w jednym żądaniu. Zamiast tego wyślij pierwsze, a następnie poczekaj na pierwsze, zanim wyślesz drugie.
Przykład
Poniższy przykład pokazuje zastosowanie wsadów za pomocą interfejsu Google Mirror API.
Przykładowe żądanie zbiorcze
POST /batch HTTP/1.1
Content-Length: content_length
content-type: multipart/mixed; boundary="===============7330845974216740156=="
accept-encoding: gzip, deflate
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_1
POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_1_token
accept: application/json
content-length: 24
{"text": "Hello there!"}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_2
POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_2_token
accept: application/json
content-length: 24
{"text": "Hello there!"}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_3
POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_3_token
accept: application/json
content-length: 24
{"text": "Hello there!"}
--===============7330845974216740156==--
Przykładowa odpowiedź wsadowa
To jest odpowiedź na przykładowe żądanie z poprzedniej sekcji.
HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Date: Tue, 22 Jan 2013 18:56:00 GMT
Expires: Tue, 22 Jan 2013 18:56:00 GMT
Cache-Control: private, max-age=0
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_1
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304
{
"kind": "glass#timelineItem",
"id": "1234567890",
"selfLink": "https://www.googleapis.com/mirror/v1/timeline/1234567890",
"created": "2012-09-25T23:28:43.192Z",
"updated": "2012-09-25T23:28:43.192Z",
"etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
"text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_2
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304
{
"kind": "glass#timelineItem",
"id": "0987654321",
"selfLink": "https://www.googleapis.com/mirror/v1/timeline/0987654321",
"created": "2012-09-25T23:28:43.192Z",
"updated": "2012-09-25T23:28:43.192Z",
"etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
"text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_3
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304
{
"kind": "glass#timelineItem",
"id": "5432109876",
"selfLink": "https://www.googleapis.com/mirror/v1/timeline/5432109876",
"created": "2012-09-25T23:28:43.192Z",
"updated": "2012-09-25T23:28:43.192Z",
"etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
"text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=--