Grupowanie żądań do interfejsu Google Analytics API

W tym dokumencie opisujemy, jak zbiorczo połączyć wywołania interfejsu API, aby zmniejszyć liczbę połączeń HTTP, które musi nawiązać klient.

Ten dokument dotyczy tworzenia żądań zbiorczych poprzez wysyłanie żądań HTTP. Jeśli zamiast tego używasz biblioteki klienta Google do wysyłania żądań zbiorczych, zapoznaj się z dokumentacją biblioteki klienta.

Przegląd

Każde połączenie HTTP realizowane przez Twojego klienta wiąże się z określonym obciążeniem. Interfejs API Google Analytics 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:

W każdym z tych przypadków zamiast wysyłać każde wywołanie oddzielnie, możesz zgrupować je w jedno żądanie HTTP. Wszystkie żądania wewnętrzne muszą trafiać do tego samego interfejsu API Google.

Jedno żądanie zbiorcze może wykonać maksymalnie 1000 wywołań. Jeśli musisz wykonać więcej wywołań, używaj wielu żądań zbiorczych.

Uwaga: system wsadowy interfejsu Google Analytics API używa tej samej składni co system przetwarzania zbiorczego OData, ale jego semantyka jest inna.

Szczegóły wsadu

Żądanie zbiorcze składa się z kilku wywołań interfejsu API połączonych w 1 żądanie HTTP, które można wysłać do interfejsu batchPath określonego w dokumencie opisującym interfejs API. Domyślną ścieżką jest /batch/api_name/api_version. W tej sekcji szczegółowo opisujemy składnię wsadu, a w dalszej części podajemy przykład.

Uwaga: zgrupowane żądania n wliczają się do limitu wykorzystania jako żądania n, a nie jako jedno żądanie. Przed przetworzeniem żądanie zbiorcze jest dzielone na zbiór żądań.

Format żądania zbiorczego

Żądanie zbiorcze to pojedyncze standardowe żądanie HTTP zawierające wiele wywołań interfejsu API Google Analytics wykorzystującego typ treści multipart/mixed. Każda część głównego żądania HTTP zawiera zagnieżdżone żądanie HTTP.

Każda część zaczyna się od własnego nagłówka HTTP Content-Type: application/http. Może też zawierać opcjonalny nagłówek Content-ID. Nagłówki części służą jednak tylko do oznaczenia początku części – są odrębne od zagnieżdżonych żądań. Gdy serwer wyodrębni żądanie zbiorcze w 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 może zawierać tylko część ścieżki 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 określisz nagłówek HTTP zarówno w żądaniu zewnętrznym, jak i w pojedynczym wywołaniu, wartość poszczególnych nagłówków zastąpi wartość nagłówka zewnętrznego żądania zbiorczego. Nagłówki pojedynczego połączenia mają zastosowanie tylko do tego połączenia.

Jeśli na przykład dla określonego wywołania podasz nagłówek Authorization, będzie on odnosił się tylko do tego wywołania. Jeśli dla zewnętrznego żądania udostępnisz nagłówek autoryzacji, będzie on stosowany do wszystkich poszczególnych wywołań, chyba że zastąpi je własnymi nagłówkami autoryzacji.

Gdy serwer otrzyma żądanie zbiorcze, stosuje do każdej części parametry zapytania i nagłówki żądania zewnętrznego (stosownie do sytuacji), a następnie traktuje każdą część tak, jakby było to 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ń zbiorczych, w tej samej kolejności co żądania.

Podobnie jak części żądania, każda część odpowiedzi zawiera pełną odpowiedź HTTP wraz z kodem stanu, nagłówkami i treścią. Podobnie jak w przypadku części żądania, każda część odpowiedzi jest poprzedzona nagłówkiem Content-Type wskazującym początek części.

Jeśli dana część żądania miała nagłówek Content-ID, odpowiadająca jej część odpowiedzi ma zgodny nagłówek Content-ID z pierwotną wartością poprzedzoną ciągiem response-, jak w poniższym 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 określone. Jeśli chcesz mieć pewność, że 2 wywołania będą występować w określonej kolejności, nie możesz wysłać ich w ramach jednego żądania. Zamiast tego wyślij pierwsze z nich samodzielnie, a następnie poczekaj na odpowiedź pierwszego z nich, a dopiero później wyślij drugie.

Przykład

W poniższym przykładzie pokazano zastosowanie 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ź wsadowa

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

Skorzystaj z tych przewodników po bibliotece klienta, aby dowiedzieć się, jak wdrożyć tworzenie wsadów w swoim języku:

Grupowanie i limit Google Analytics

Dzięki grupowaniu nie musisz tworzyć wielu żądań HTTP, dlatego każde żądanie do interfejsu Google Analytics API w ramach żądania zbiorczego będzie wliczane do dziennego limitu projektu. Domyślnie projekt może wysyłać do 50 000 żądań dziennie. Grupowanie w grupie nie pomoże zmieścić się w limicie.

Z wyjątkiem zbiorczych żądań uprawnień użytkownika do zapisu (usuwania, wstawiania, aktualizacji) nadal obowiązują wszystkie limity liczby żądań. Na przykład interfejs API podstawowego raportowania jest ograniczony do 10 żądań równoczesnych na widok (profil). Grupowanie nie pomoże zmieścić się w tym limicie.

Limit 1,5 zapytań na sekundę na identyfikator konta dotyczy żądań zapisu w interfejsie Management API i żądań zapisu do interfejsu API do obsługi administracyjnej. Z tego względu grupowanie tych żądań zapisu może nie poprawić wydajności.