Wysyłanie żądań zbiorczych

Z tego dokumentu dowiesz się, jak grupować wywołania interfejsu API, aby zmniejszyć liczbę połączeń HTTP, które musi nawiązać klient.

Ten dokument dotyczy wysyłania żądania zbiorczego przez wysłanie żądania HTTP. Jeśli zamiast tego używasz biblioteki klienta Google do wysyłania operacji grupowych, zapoznaj się z dokumentacją biblioteki klienta.

Omówienie

Każde połączenie HTTP nawiązywane przez klienta powoduje pewien narzut. Interfejs Google Search Console API obsługuje grupowanie, dzięki czemu klient może umieścić kilka wywołań interfejsu API w jednym żądaniu HTTP.

Przykłady sytuacji, w których warto użyć 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 (nie miała połączenia z internetem), więc aplikacja musi zsynchronizować dane lokalne z serwerem, wysyłając wiele aktualizacji i usunąć.

W obu przypadkach zamiast wysyłać każde wywołanie osobno możesz je pogrupować w pojedyncze żądanie HTTP. Wszystkie żądania wewnętrzne muszą być kierowane do tego samego interfejsu Google API.

W jednym zbiorczym żądaniu możesz utworzyć maksymalnie 1000 wywołań. Jeśli musisz wykonać więcej wywołań, użyj wielu żądań zbiorczych.

Uwaga: system przetwarzania zbiorczego interfejsu Google Search Console API używa tej samej składni co system przetwarzania zbiorczego OData, ale ma inną semantykę.

Szczegóły wsadu

Żądanie zbiorcze składa się z kilku wywołań interfejsu API połączonych w jedno żądanie HTTP, które można wysłać do batchPath określonego w dokumencie wyszukiwania interfejsu API. Ścieżka domyślna to /batch/api_name/api_version. W tej sekcji znajdziesz szczegółowe informacje o składni zbiorczej. Dalej znajdziesz przykład.

Uwaga: zestaw n żądań zebranych w jedną grupę jest traktowany jako n żądań, a nie jako jedno żądanie. Przed przetworzeniem żądanie zbiorcze jest dzielone na zestaw żądań.

Format żądania zbiorczego

Żądanie zbiorcze to pojedyncze standardowe żądanie HTTP zawierające wiele wywołań interfejsu API Google Search Console, używające typu treści multipart/mixed. Każda część tego głównego żądania HTTP zawiera zagnieżdżone żądanie HTTP.

Każda część zaczyna się od własnego nagłówka Content-Type: application/http HTTP. Może też mieć opcjonalny nagłówek Content-ID. Nagłówki części służą jednak tylko do oznaczenia początku danej części i są niezależne od zagnieżdżonego żądania. Gdy serwer wyodrębni żądanie zbiorcze na osobne żądania, nagłówki części są ignorowane.

Treść każdej części to kompletne żądanie HTTP z własnym czasownikiem, adresem URL, nagłówkami i treścią. Żądanie HTTP musi zawierać tylko ścieżkę adresu URL. W żądaniach zbiorczych nie można podawać pełnych adresów URL.

Nagłówki HTTP żądania zbiorczego zewnętrznego, z wyjątkiem nagłówków Content-, np. Content-Type, mają zastosowanie do każdego żądania w zbiorczym żądaniu. Jeśli dany nagłówek HTTP jest określony zarówno w żądaniu zewnętrznym, jak i w poszczególnym wywołaniu, wartość nagłówka pojedynczego wywołania zastąpi wartość nagłówka zewnętrznego żądania zbiorczego. Nagłówki pojedynczego połączenia dotyczą tylko tego połączenia.

Jeśli na przykład podasz nagłówek autoryzacji dla określonego wywołania, będzie on stosowany tylko do tego wywołania. Jeśli w żądaniu zewnętrznym podasz nagłówek Authorization, będzie on dotyczyć wszystkich poszczególnych wywołań, chyba że zostaną zastąpione przez własne nagłówki Authorization.

Gdy serwer otrzyma żądanie zbiorcze, zastosuje parametry zapytania i nagłówki żądania zewnętrznego (w odpowiednich przypadkach) do każdej części, a potem potraktuje każdą część tak, jakby była osobnym żądaniem HTTP.

Odpowiedź na żądanie zbiorcze

Odpowiedź serwera to pojedyncza standardowa odpowiedź HTTP z typem treści multipart/mixed. Każda część jest odpowiedzią na jedno z żądań w żądaniu zbiorczym, w tej samej kolejności co żądania.

Podobnie jak części żądania, każda część odpowiedzi zawiera pełną odpowiedź HTTP, w tym kod stanu, nagłówki i treść. Podobnie jak w przypadku części żądania, każdą część odpowiedzi poprzedza nagłówek Content-Type, który wskazuje początek części.

Jeśli dana część żądania zawierała nagłówek Content-ID, odpowiadająca jej część odpowiedzi zawiera pasujący nagłówek Content-ID, a pierwotna wartość jest poprzedzona ciągiem znaków response-, jak w tym przykładzie.

Uwaga: serwer może wykonywać wywołania w dowolnej kolejności. Nie licz na ich wykonanie w kolejności, w jakiej zostały one określone. Jeśli chcesz mieć pewność, że w danej kolejności będą wykonywane 2 wywołania, nie możesz wysłać ich w jednym żądaniu. Zamiast tego wyślij pierwsze z nich samodzielnie, a następnie poczekaj na odpowiedź, zanim wyślesz kolejne.

Przykład

Ten przykład pokazuje użycie grupowania w ogólnym (fikcyjnym) interfejsie API o nazwie Farm API. Jednak te same pojęcia są używane w przypadku interfejsu Search Console API.

Przykładowe żądanie zbiorcze

POST /batch/farm/v1 HTTP/1.1
Authorization: Bearer your_auth_token
Host: www.googleapis.com
Content-Type: multipart/mixed; boundary=batch_foobarbaz
Content-Length: total_content_length

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item1:[e-mail]>

GET /farm/v1/animals/pony

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item2:[e-mail]>

PUT /farm/v1/animals/sheep
Content-Type: application/json
Content-Length: part_content_length
If-Match: "etag/sheep"

{
  "animalName": "sheep",
  "animalAge": "5"
  "peltColor": "green",
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item3:[e-mail]>

GET /farm/v1/animals
If-None-Match: "etag/animals"

--batch_foobarbaz--

Przykładowa odpowiedź zbiorcza

Oto odpowiedź na przykładowe żądanie z poprzedniej sekcji.

HTTP/1.1 200
Content-Length: response_total_content_length
Content-Type: multipart/mixed; boundary=batch_foobarbaz

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item1:[e-mail]>

HTTP/1.1 200 OK
Content-Type application/json
Content-Length: response_part_1_content_length
ETag: "etag/pony"

{
  "kind": "farm#animal",
  "etag": "etag/pony",
  "selfLink": "/farm/v1/animals/pony",
  "animalName": "pony",
  "animalAge": 34,
  "peltColor": "white"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item2:[e-mail]>

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: response_part_2_content_length
ETag: "etag/sheep"

{
  "kind": "farm#animal",
  "etag": "etag/sheep",
  "selfLink": "/farm/v1/animals/sheep",
  "animalName": "sheep",
  "animalAge": 5,
  "peltColor": "green"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item3:[e-mail]>

HTTP/1.1 304 Not Modified
ETag: "etag/animals"

--batch_foobarbaz--