1 sierpnia 2020 roku wycofaliśmy 1 sposób globalny, czyli wsadowy punkt końcowy HTTP (www.googleapis.com/batch), który ogłosiliśmy na blogu Google Developers. Inne sposoby grupowania nadal działają, jak opisano na pozostałej stronie. Jeśli Twój kod korzysta z globalnego punktu końcowego wsadów HTTP, w poście na blogu znajdziesz instrukcje przejścia na inne metody, takie jak punkty końcowe HTTP wsadowych operacji określonych dla interfejsu API (www.googleapis.com/batch/API/VERSION).
W tym dokumencie pokazujemy, jak grupować wywołania interfejsu API, aby zmniejszyć liczbę połączeń HTTP, które musi nawiązać klient.
Ten dokument dotyczy wysyłania zbiorczego żądania przez żądanie HTTP. Jeśli zamiast tego do wysyłania żądań zbiorczych używasz biblioteki klienta Google, zapoznaj się z dokumentacją za pomocą biblioteki klienta.
Opis
Każde połączenie HTTP, które klient tworzy, wiąże się z określonym kosztem. Interfejs Google Ad Experience Report API obsługuje grupowanie, dzięki czemu klient może wysłać kilka wywołań interfejsu API do jednego żądania HTTP.
Przykłady zastosowania grupowania:
- Używasz interfejsu API od niedawna i masz dużo danych do przesłania.
- Użytkownik wprowadził dane w trybie offline (bez połączenia z internetem), więc Twoja aplikacja musi zsynchronizować lokalne dane z serwerem poprzez wysłanie wielu aktualizacji i usunięcia.
W każdym przypadku zamiast wysyłać osobne wywołanie, możesz połączyć je w jedno żądanie HTTP. Wszystkie wewnętrzne żądania muszą należeć 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 wielu żądań zbiorczych.
Uwaga: system wsadowy interfejsu API raportu reklam Google używa tej samej składni co system przetwarzania wsadowego danych, 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 wykrywania interfejsu API. Ścieżka domyślna to /batch/api_name/api_version. Ta sekcja zawiera szczegółowy opis wsadu. Później jest też przykład.
Uwaga: zestaw n żądań zbiorczych jest wliczany do limitu wykorzystania jako n żądania, 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 Google Ad Experience Report API przy użyciu typu treści multipart/mixed. W ramach tego głównego żądania HTTP każda część zawiera zagnieżdżone żądanie HTTP.
Każda część ma własny nagłówek HTTP Content-Type: application/http. Może też mieć opcjonalny nagłówek Content-ID. Nagłówki części strony są jednak tylko po to, aby oznaczyć początek części. Są one niezależne od zagnieżdżonego żądania. Gdy serwer wyodrębni pakiet wsadowy do oddzielnych żądań, nagłówki części zostaną zignorowane.
Treść każdej części jest pełnym żądaniem HTTP z własnym czasownikiem, adresem URL, nagłówkami i treścią. Żądanie HTTP może zawierać tylko część ścieżki adresu URL; pełne adresy URL nie są dozwolone w żądaniach zbiorczych.
Nagłówki HTTP zewnętrznego żądania zbiorczego, z wyjątkiem nagłówków Content-, takich jak Content-Type, mają zastosowanie do wszystkich żądań w grupie. Jeśli określisz określony nagłówek HTTP zarówno w żądaniu zewnętrznym, jak i w pojedynczym wywołaniu, wartość tego nagłówka zastąpi wartość zewnętrznego nagłówka żądania zbiorczego. Nagłówki pojedynczego połączenia dotyczą tylko tego połączenia.
Jeśli na przykład podasz nagłówek autoryzacji dla określonego połączenia, to ten nagłówek będzie dotyczył tylko 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ą go własnymi nagłówkami autoryzacji.
Gdy serwer odbiera zbiorowe żądanie, stosuje do wybranych części zewnętrzne parametry zapytania i nagłówki (a potem 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 tej samej kolejności co żądania.
Podobnie jak w przypadku części żądania, każda część odpowiedzi zawiera pełną odpowiedź HTTP wraz z kodem stanu, nagłówkami i treścią. Tak jak w przypadku części żądania, każda część odpowiedzi jest poprzedzona nagłówkiem Content-Type, który oznacza początek części.
Jeśli dana część żądania ma nagłówek Content-ID, to odpowiedni fragment odpowiedzi ma pasujący nagłówek Content-ID z pierwotną wartością poprzedzającą ciąg response-, jak pokazano w poniższym przykładzie.
Uwaga: serwer może nawiązywać połączenia w dowolnej kolejności. Nie są liczone w takiej kolejności, w jakiej zostały przez Ciebie określone. Jeśli chcesz mieć pewność, że 2 wywołania mają miejsce w jednej kolejności, nie możesz przesłać ich w jednym żądaniu. Zamiast tego możesz wysłać pierwsze, a następnie poczekać na pierwsze, zanim wyślesz drugie.
Przykład
Poniższy przykład ilustruje użycie grupowania przy użyciu interfejsu Google Ad Experience Report API.
Przykładowe żądanie zbiorcze
POST /batch/v1?key=key HTTP/1.1 Content-Type: multipart/mixed; boundary=batch_aer --batch_aer Content-Type: application/http Content-ID: id1 GET /v1/sites/http%3A%2F%2F/site1%2F HTTP/1.1 --batch_aer Content-Type: application/http Content-ID: id2 GET /v1/sites/http%3A%2F%2F/site2%2F HTTP/1.1 --batch_aer--
Przykładowa odpowiedź zbiorcza
To jest odpowiedź na przykładowe żądanie z poprzedniej sekcji.
HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_aer
--batch_aer
Content-Type: application/http
Content-ID: response-id1
HTTP/1.1 200 OK
Content-Type: application/json
{
"reviewedSite": "site1",
"mobileSummary": {
"lastChangeTime": "2019-02-05T09:46:26.521747Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site1/",
"filterStatus": "OFF"
},
"desktopSummary": {
"lastChangeTime": "2019-02-07T23:07:29.017206Z",
"betterAdsStatus": "FAILING",
"enforcementTime": "2018-02-15T15:00:00Z",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site1/",
"filterStatus": "ON"
}
}
--batch_aer
Content-Type: application/http
Content-ID: response-id2
HTTP/1.1 200 OK
Content-Type: application/json
{
"reviewedSite": "site2",
"mobileSummary": {
"lastChangeTime": "2018-03-06T16:06:33.375851Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site2/",
"filterStatus": "OFF"
},
"desktopSummary": {
"lastChangeTime": "2018-03-06T16:06:33.375851Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site2/",
"filterStatus": "OFF"
}
}
--batch_aer--