Grupowanie żądań interfejsu API Google Analytics

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.

Przegląd

Każde połączenie HTTP, które klient tworzy, wiąże się z określonym kosztem. Interfejs Google Analytics API obsługuje grupowanie, aby umożliwić klientowi wykonanie kilku wywołań interfejsu API w jednym żądaniu HTTP.

Przykłady zastosowania grupowania:

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 dla interfejsu Google Analytics API 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 Analytics API korzystających z 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 pokazuje wykorzystanie grupowania za pomocą interfejsu Google Analytics API.

Przykładowe żądanie zbiorcze

POST /batch/analytics/v3 HTTP/1.1
Host: www.googleapis.com
Content-length: 731
Content-type: multipart/mixed; boundary=batch_0123456789
Authorization: Bearer ya29.5gFZooleNoSpGqYOOF0eFciUGz1x26k9GagZoW7HJCogWlCoNOotxlZPo7bDbwo1ykDq
--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 68


{
 "name": "Campaign Group",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 67


{
 "name": "Campaign Type",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789--

Przykładowa odpowiedź zbiorcza

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

HTTP/1.1 200 OK
Content-length: 1876
X-xss-protection: 1; mode=block
X-content-type-options: nosniff
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Vary: Origin,X-Origin
Server: GSE
Cache-control: private, max-age=0
Date: Wed, 02 Sep 2015 21:36:35 GMT
X-frame-options: SAMEORIGIN
Content-type: multipart/mixed; boundary=batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/L-Y_3uM9BpST8Sea-SJDRQ7N7vE"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 548

{"kind":"analytics#customDimension","id":"ga:dimension18","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Group","index":18,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:34.143Z","updated":"2015-09-02T21:36:34.143Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension18","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/VN-21fLS1T0Qko3pHEB5fi8vYJ8"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 547

{"kind":"analytics#customDimension","id":"ga:dimension19","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Type","index":19,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:35.099Z","updated":"2015-09-02T21:36:35.099Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension19","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q--

Biblioteki klienta

Zapoznaj się z tymi przewodnikami po bibliotece klienta, aby dowiedzieć się, jak wdrożyć w swoim języku grupowanie:

Grupowanie i limit Google Analytics

Grupowanie może zaoszczędzić na kosztach tworzenia wielu żądań HTTP w każdym żądaniu interfejsu Google Analytics API, co spowoduje zaliczenie limitu dziennego projektu. Domyślnie projekt może przesłać do 50 tys. żądań dziennie. Grupowanie nie pomoże przekroczyć tego limitu.

Z wyjątkiem zgrupowanych żądań uprawnień do zapisu (usuwania, wstawiania i aktualizowania) nadal obowiązują wszystkie ograniczenia liczby żądań. Na przykład interfejs Core Reporting API jest ograniczony do 10 żądań równoczesnych na widok danych (profil). Grupowanie nie pomoże przekroczyć tego limitu.

Limit 1,5 zapytania na sekundę (QPS) na identyfikator konta dotyczy żądań zapisu interfejsu API zarządzania i żądań zapisu interfejsu API. Dlatego grupowanie tych żądań zapisu może nie poprawić wydajności.