Ten dokument zawiera pełne informacje na temat zapytań i odpowiedzi interfejsu Core Reporting API w wersji 3.0.
Wstęp
Wysyłasz zapytania do interfejsu Core Reporting API w związku z danymi raportu Google Analytics. Każde zapytanie wymaga identyfikatora widoku (profilu), daty rozpoczęcia i zakończenia oraz co najmniej 1 wskaźnika. Możesz też podać dodatkowe parametry zapytania, np. wymiary, filtry i segmenty, aby doprecyzować zapytanie. Z przewodnika z omówieniem dowiesz się, jak współdziałają te wszystkie pojęcia.
Prośba
Interfejs API udostępnia jedną metodę wysyłania żądań danych:
analytics.data.ga.get()
Ta metoda jest dostępna w różnych bibliotekach klienta i ma interfejsy przeznaczone do ustawiania parametrów zapytania w różnych językach.
Do interfejsu API można też wysyłać zapytania jako punkt końcowy wykorzystujący protokół REST:
Authorization: Bearer {oauth2-token} GET https://www.googleapis.com/analytics/v3/data/ga ?ids=ga:12345 &start-date=2008-10-01 &end-date=2008-10-31 &metrics=ga:sessions,ga:bounces
Każdy parametr zapytania w adresie URL określa parametr zapytania w interfejsie API, który musi być zakodowany w adresie URL.
Podsumowanie parametrów zapytania
W tabeli poniżej znajdziesz podsumowanie wszystkich parametrów zapytania akceptowanych przez interfejs API podstawowego raportowania. Kliknij nazwę parametru, aby wyświetlić jego szczegółowy opis.
Nazwa | Wartość | Wymagane | Podsumowanie |
---|---|---|---|
ids |
string |
tak | Unikalny identyfikator tabeli mający postać ga:XXXX, gdzie XXXX to identyfikator widoku danych (profilu) Analytics, z którego zapytanie ma pobierać dane. |
start-date |
string |
tak |
Data rozpoczęcia pobierania danych Analytics. Żądania mogą zawierać datę rozpoczęcia w formacie YYYY-MM-DD lub datę względną (np. today , yesterday lub NdaysAgo , gdzie N to dodatnia liczba całkowita).
|
end-date |
string |
tak |
Data zakończenia pobierania danych Analytics. Żądanie może zawierać datę zakończenia w formacie YYYY-MM-DD lub datę względną (np.
today , yesterday lub NdaysAgo , gdzie N to dodatnia liczba całkowita).
|
metrics |
string |
tak |
Lista danych rozdzielonych przecinkami, np. ga:sessions,ga:bounces .
|
dimensions |
string |
nie |
Lista wymiarów rozdzielonych przecinkami związanych z danymi Analytics, np. ga:browser,ga:city .
|
sort |
string |
nie | Lista rozdzielonych przecinkami wymiarów i danych wskazujących kolejność sortowania i kierunek sortowania zwracanych danych. |
filters |
string |
nie | Filtry wymiarów lub danych, które ograniczają ilość danych zwracanych w odpowiedzi na Twoje żądanie. |
segment |
string |
nie | Segmentuje dane zwrócone w odpowiedzi na żądanie. |
samplingLevel |
string |
nie | Żądany poziom próbkowania. Dozwolone wartości:
|
include-empty-rows |
boolean |
nie | Wartość domyślna to prawda. Jeśli ma wartość fałsz, wiersze, w których wszystkie wartości wskaźników wynoszą 0, są pomijane w odpowiedzi. |
start-index |
integer |
nie |
Pierwszy wiersz danych do pobrania, począwszy od 1. Używaj tego parametru jako mechanizmu podziału na strony razem z parametrem max-results .
|
max-results |
integer |
nie | Maksymalna liczba wierszy do uwzględnienia w odpowiedzi. |
output |
string |
nie |
Żądany typ wyjściowy danych Analytics zwracanych w odpowiedzi.
Akceptowane wartości to json i dataTable . Wartość domyślna: json .
|
fields |
string |
nie | Selektor określający podzbiór pól do uwzględnienia w odpowiedzi. |
prettyPrint |
string |
nie |
Zwraca odpowiedź z wcięciami i podziałami wierszy. Wartość domyślna: false .
|
userIp |
string |
nie | Określa adres IP użytkownika, dla którego wykonywane jest wywołanie interfejsu API. Służy do ograniczania wykorzystania na adres IP. |
quotaUser |
string |
nie | Alternatywa dla parametru userIp w przypadku, gdy adres IP użytkownika jest nieznany. |
access_token |
string |
nie | Jednym z możliwych sposobów dostarczenia tokenu OAuth 2.0. |
callback |
string |
nie | Nazwa funkcji wywołania zwrotnego JavaScriptu, która obsługuje odpowiedź. Używany w żądaniach JSON-P JavaScript. |
key |
string |
nie | Służy do autoryzacji OAuth 1.0a w celu określenia aplikacji, która ma uzyskać limit. Przykład: key=AldefliuhSFADSfasdfasdfASdf . |
Szczegóły parametru zapytania
ids
ids=ga:12345
ga:
z identyfikatorem widoku (profilu) Analytics. Identyfikator widoku danych (profilu) możesz pobrać za pomocą metody analytics.management.profiles.list
, która udostępnia obiekt id
w zasobie widoku (profile) w interfejsie Google Analytics Management API.
data rozpoczęcia
start-date=2009-04-20
start-date
i end-date
, serwer zwróci błąd. Daty możesz ustawić dla określonej daty przy użyciu wzorca YYYY-MM-DD
lub względnego z użyciem today
, yesterday
lub wzorca NdaysAgo
.
Wartości muszą być zgodne z wartością [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
.
start-date
najwcześniejsza prawidłowa wartość to 2005-01-01
.
Nie ma górnego limitu daty rozpoczęcia.Przykładowy zakres dat z ostatnich 7 dni (od wczoraj) z użyciem dat względnych:
&start-date=7daysAgo &end-date=yesterday
data zakończenia
end-date=2009-05-20
start-date
i end-date
, serwer zwróci błąd. Daty możesz ustawić dla określonej daty przy użyciu wzorca YYYY-MM-DD
lub względnego z użyciem today
, yesterday
lub wzorca NdaysAgo
.
Wartości muszą być zgodne z wartością [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
.
end-date
to 2005-01-01
. end-date
nie ma górnego limitu. Przykładowy zakres dat w ciągu ostatnich 10 dni (od dziś) z wykorzystaniem dat względnych:
&start-date=9daysAgo &end-date=today
wymiary
dimensions=ga:browser,ga:city
dimensions
dzieli dane według wspólnych kryteriów, np. ga:browser
lub ga:city
.
Możesz zapytać o łączną liczbę odsłon w witrynie, ale ciekawsze może być podanie liczby takich odsłon z podziałem na poszczególne przeglądarki. W takim przypadku zobaczysz liczbę odsłon stron w przeglądarkach Firefox, Internet Explorer, Chrome itd.
Gdy używasz dimensions
w żądaniu danych, pamiętaj o tych ograniczeniach:
- W każdym zapytaniu możesz podać maksymalnie 7 wymiarów.
- Nie możesz wysłać zapytania składającego się tylko z wymiarów. Musisz połączyć żądane wymiary z co najmniej 1 rodzajem danych.
- W ramach tego samego zapytania można wysyłać tylko niektóre wymiary. Aby sprawdzić, których wymiarów możesz używać razem, użyj prawidłowego narzędzia do łączenia kombinacji w narzędziu do sprawdzania wymiarów i danych.
metrics
metrics=ga:sessions,ga:bounces
dimensions
, zwracane dane zawierają zbiorcze wartości dla żądanego zakresu dat, takie jak łączna liczba odsłon lub łączna liczba odrzuceń. Przy wysyłaniu żądania wymiarów wartości są jednak posegmentowane według wartości wymiaru. Na przykład żądanie ga:pageviews
z parametrem ga:country
zwraca łączną liczbę odsłon w poszczególnych krajach.
Podczas przesyłania żądania danych pamiętaj o tych kwestiach:- Każde żądanie musi zawierać co najmniej 1 rodzaj danych; żądanie nie może zawierać tylko wymiarów.
- W przypadku każdego zapytania możesz podać maksymalnie 10 rodzajów danych.
- Większość kombinacji wskaźników z wielu kategorii można stosować razem, o ile nie zostały określone żadne wymiary.
- Dane mogą być używane w połączeniu z innymi wymiarami lub danymi, ale tylko wtedy, gdy w przypadku tego rodzaju danych mają zastosowanie prawidłowe kombinacje. Więcej informacji znajdziesz w dokumentacji wymiarów i danych.
sortuj
sort=ga:country,ga:browser
Lista danych i wymiarów wskazujących kolejność sortowania i kierunek sortowania zwracanych danych.
- Kolejność sortowania jest określana według kolejności od lewej do prawej wymienionych danych i wymiarów.
- Sortowanie według direction jest domyślnie ustawione na rosnącą i można je zmienić na malejące, używając prefiksu znaku minusa (
-
) w żądanym polu.
Sortowanie wyników zapytania umożliwia podawanie różnych pytań dotyczących danych. Przykładowo w odpowiedzi na pytanie: „W których krajach są najpopularniejsze i z jakich przeglądarek korzystają najczęściej?”.
możesz utworzyć zapytanie z tym parametrem. Jest sortowane najpierw według kolumny ga:country
, a następnie według wartości ga:browser
, zarówno w kolejności rosnącej:
sort=ga:country,ga:browser
Aby odpowiedzieć na pytanie „Jakie są moje najpopularniejsze przeglądarki i w których krajach ich używają najczęściej?”, możesz utworzyć zapytanie z poniższym parametrem. Jest sortowane najpierw według kolumny
ga:browser
, a następnie według kolumny ga:country
(oba w kolejności rosnącej):sort=ga:browser,ga:country
Korzystając z parametru sort
, pamiętaj o tych kwestiach:
- Sortuj tylko według wymiarów lub wartości danych użytych w parametrach
dimensions
lubmetrics
. Jeśli żądanie zostanie posortowane według pola, które nie jest wskazane w parametrach wymiarów lub danych, wystąpi błąd. - Domyślnie ciągi tekstowe są sortowane w kolejności alfabetycznej rosnąco według języka en-US.
- Liczby są domyślnie sortowane w kolejności rosnącej.
- Daty są domyślnie sortowane w kolejności rosnącej według daty.
filtry
filters=ga:medium%3D%3Dreferral
Parametr ciągu zapytania filters
ogranicza ilość danych zwracanych w wyniku żądania. Aby użyć parametru filters
, podaj wymiar lub dane do filtrowania, a po nim wyrażenie filtra. Na przykład to zapytanie żąda ga:pageviews
i ga:browser
dla widoku (profilu) 12134
, gdzie wymiar ga:browser
zaczyna się ciągiem Firefox
:
https://www.googleapis.com/analytics/v3/data/ga ?ids=ga:12134 &dimensions=ga:browser &metrics=ga:pageviews &filters=ga:browser%3D~%5EFirefox &start-date=2007-01-01 &end-date=2007-12-31
Odfiltrowane zapytania ograniczają liczbę wierszy, które są uwzględniane w wynikach (lub nie). Każdy wiersz w wyniku jest sprawdzany pod kątem zgodności z filtrem. Jeśli filtr zostanie dopasowany, wiersz zostaje zachowany, a jeśli nie, wynik jest usuwany.
- Kodowanie adresów URL: biblioteki klienta interfejsów API Google automatycznie kodują operatory filtrów.
- Filtrowanie wymiarów: filtrowanie ma miejsce przed zagregowaniem jakichkolwiek wymiarów, dzięki czemu zwracane dane odzwierciedlają sumę tylko dla odpowiednich wymiarów. W powyższym przykładzie liczba odsłon byłaby równa tylko odsłonom stron, w których przeglądarka jest Firefox.
- Filtrowanie danych: filtrowanie według danych ma miejsce po agregacji danych.
- Prawidłowe kombinacje: możesz filtrować według wymiaru lub danych, które nie są uwzględnione w zapytaniu, pod warunkiem że wszystkie wymiary/dane w żądaniu oraz filtr to prawidłowe kombinacje. Możesz na przykład utworzyć zapytanie o datowaną listę odsłon przefiltrowaną według konkretnej przeglądarki. Więcej informacji znajdziesz w dokumentacji wymiarów i danych.
Składnia filtra
Pojedynczy filtr ma postać:
ga:name operator expression
W tej składni:
- nazwa – nazwa wymiaru lub danych, według których chcesz filtrować. Na przykład:
ga:pageviews
filtruje dane odsłon. - operator – określa typ dopasowania filtra, który ma być użyty. Operatory dotyczą wymiarów lub danych.
- wyrażenie – określa wartości, które mają być uwzględnione w wynikach lub z nich wykluczone. Wyrażenia korzystają ze składni wyrażeń regularnych.
Filtruj operatory
Dostępnych jest 6 operatorów filtrowania wymiarów i 6 operatorów filtrowania wskaźników. Operatory muszą być zakodowane na potrzeby adresu URL, aby zostały uwzględnione w ciągach zapytań w adresach URL.
Wskazówka: używaj eksploratora zapytań dotyczących pliku danych, aby zaprojektować filtry wymagające kodowania adresów URL, ponieważ Eksplorator zapytań automatycznie koduje adresy URL zawierające ciągi i spacje.
Operator | Opis | Formularz zakodowany z adresem URL | Przykłady |
---|---|---|---|
== |
Równa się | %3D%3D |
Zwraca wyniki, w przypadku których czas na stronie wynosi dokładnie 10 sekund:filters=ga:timeOnPage%3D%3D10 |
!= |
Różne od | !%3D |
Zwraca wyniki, w przypadku których czas na stronie nie wynosi 10 sekund:filters=ga:timeOnPage!%3D10 |
> |
To więcej niż | %3E |
Zwraca wyniki, w przypadku których czas spędzony na stronie przekracza 10 sekund:filters=ga:timeOnPage%3E10 |
< |
To mniej niż | %3C |
Zwraca wyniki, w przypadku których czas spędzony na stronie nie przekracza 10 sekund:filters=ga:timeOnPage%3C10 |
>= |
Ma wartość większą lub równą | %3E%3D |
Zwraca wyniki, w przypadku których czas spędzony na stronie wynosi co najmniej 10 sekund:filters=ga:timeOnPage%3E%3D10 |
<= |
Ma wartość mniejszą lub równą | %3C%3D |
Zwraca wyniki, w przypadku których czas spędzony na stronie nie przekracza 10 sekund:filters=ga:timeOnPage%3C%3D10 |
Operator | Opis | Formularz zakodowany z adresem URL | Przykład |
---|---|---|---|
== |
Dopasowanie ścisłe | %3D%3D |
Dane zbiorcze dotyczące miasta Irvine:filters=ga:city%3D%3DIrvine |
!= |
Nie pasuje | !%3D |
Dane zbiorcze, w przypadku których miasto nie jest Irvine:filters=ga:city!%3DIrvine |
=@ |
Zawiera podłańcuch | %3D@ |
Dane zbiorcze, w przypadku których miasto zawiera York:filters=ga:city%3D@York |
!@ |
Nie zawiera podłańcucha | !@ |
Dane zbiorcze, w przypadku których miasto nie zawiera słowa York:filters=ga:city!@York |
=~ |
Zawiera dopasowanie do wyrażenia regularnego | %3D~ |
Zagregowane dane, w których miasto zaczyna się od nowego:filters=ga:city%3D~%5ENew.* (%5E to adres URL zakodowany ze znaku ^, który zakotwicza wzorzec na początku ciągu znaków). |
!~ |
Brak dopasowania do wyrażenia regularnego | !~ |
Wskaźniki zbiorcze, w przypadku których nazwa miasta nie zaczyna się od słowa Nowy: filters=ga:city!~%5ENew.* |
Filtruj wyrażenia
Istnieje kilka ważnych reguł dotyczących wyrażeń filtra:
- Znaki zarezerwowane w adresie URL – znaki takie jak
&
muszą być zakodowane w zwykły sposób. - Znaki zarezerwowane – gdy występują w wyrażeniu, średnik i przecinek musi być poprzedzony ukośnikiem lewym:
- średnik
\;
- przecinek
\,
- średnik
- Wyrażenia regularne – w wyrażeniach filtra możesz też używać wyrażeń regularnych, używając operatorów
=~
i!~
. Ich składnia jest podobna do wyrażeń regularnych w Perl i ma te dodatkowe reguły:- Maksymalna długość 128 znaków – wyrażenia regularne dłuższe niż 128 znaków powodują zwrócenie kodu stanu
400 Bad Request
przez serwer. - Wielkość liter – w dopasowywaniu wyrażeń regularnych wielkość liter nie jest rozróżniana.
- Maksymalna długość 128 znaków – wyrażenia regularne dłuższe niż 128 znaków powodują zwrócenie kodu stanu
Łączenie filtrów
Filtry można łączyć za pomocą wartości logicznych OR
i AND
. Dzięki temu możesz skutecznie zwiększyć limit 128 znaków w wyrażeniu filtra.
LUB
Operator OR
jest definiowany za pomocą przecinka (,
). Ma on pierwszeństwo przed operatorem AND
i NIE można go używać do łączenia wymiarów i danych w tym samym wyrażeniu.
Przykłady: (każdy musi być zakodowany na potrzeby adresu URL)
Kraj to (Stany Zjednoczone LUB Kanada):
ga:country==United%20States,ga:country==Canada
Użytkownicy przeglądarki Firefox w systemach operacyjnych Windows LUB Macintosh:
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh
ORAZ
Operator AND
jest definiowany przy użyciu średnika (;
).
Jest poprzedzony operatorem OR
i może być używany do łączenia wymiarów i danych w tym samym wyrażeniu.
Przykłady: (każdy musi być zakodowany na potrzeby adresu URL)
Kraj to Stany Zjednoczone ORAZ przeglądarka to Firefox:
ga:country==United%20States;ga:browser==Firefox
Kraj to Stany Zjednoczone ORAZ język nie zaczyna się od „en”:
ga:country==United%20States;ga:language!~^en.*
System operacyjny (Windows LUB Macintosh) ORAZ przeglądarka (Firefox LUB Chrome):
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome
Kraj to Stany Zjednoczone ORAZ liczba sesji jest większa niż 5:
ga:country==United%20States;ga:sessions>5
podziel na segmenty
segment=gaid::-10
segment=sessions::condition::ga:medium%3D%3Dreferral
segment=users::condition::ga:browser%3D%3DChrome
Szczegółowe informacje o tym, jak zażądać segmentu przy użyciu interfejsu API podstawowego raportowania, znajdziesz w przewodniku dla programistów dotyczącym segmentów.
Ogólne informacje o segmentach znajdziesz w artykułach Informacje o funkcjach segmentów i Segmenty w Centrum pomocy.
Wymiary i dane dozwolone w segmentach.
W segmentach nie można używać wszystkich wymiarów i danych. Aby sprawdzić, które wymiary i dane są dozwolone w segmentach, otwórz
Eksplorator wymiarów i danych.
samplingLevel
samplingLevel=DEFAULT
DEFAULT
– zwraca odpowiedź z rozmiarem próbki, który równoważy szybkość i dokładność.FASTER
– zwraca szybką odpowiedź z mniejszą próbką.HIGHER_PRECISION
– zwraca dokładniejszą odpowiedź przy użyciu dużego rozmiaru próbki, ale może to spowodować wolniejsze odpowiedzi.
DEFAULT
.uwzględnij-puste-wiersze
include-empty-rows=true
start-index
start-index=10
1
. (Indeksy wyników są oparte na liczbie 1. Oznacza to, że pierwszy wiersz to wiersz 1
, a nie wiersz 0
. Używaj tego parametru jako mechanizmu podziału na strony razem z parametrem max-results
w sytuacjach, gdy wartość totalResults
przekracza 10 000 i chcesz pobierać wiersze zindeksowane od 10 001.max-results
max-results=100
start-index
, aby pobierać podzbiór elementów, lub używać go samodzielnie do ograniczenia liczby zwracanych elementów, zaczynając od pierwszego.
Jeśli nie podano max-results
, zapytanie zwraca domyślnie maksymalną liczbę 1000 wierszy.ga:country
możliwych jest mniej niż 300 wartości, więc przy segmentowaniu tylko według kraju nie uda Ci się uzyskać więcej niż 300 wierszy nawet wtedy, gdy ustawisz wyższą wartość max-results
.wynik
output=dataTable
json
– w odpowiedzi zwraca domyślną właściwośćrows
zawierającą obiekt JSON.dataTable
– w odpowiedzi zwraca właściwośćdataTable
zawierającą obiekt Data Table (Tabela danych). ObiektuData Table
można używać bezpośrednio z wizualizacjami Map Google.
pola
fields=rows,columnHeaders(name,dataType)
Określa pola, które mają zostać zwrócone w odpowiedzi częściowej. Jeśli w odpowiedzi interfejsu API używasz tylko podzbioru pól, możesz użyć parametru fields
, aby określić, które pola mają zostać uwzględnione.
Format wartości parametru żądania pól jest oparty na składni XPath. Podsumowanie obsługiwanej składni znajdziesz poniżej.
- Aby wybrać wiele pól, użyj listy rozdzielanej przecinkami.
- Użyj funkcji
a/b
, aby wybrać pole b zagnieżdżone w polu a. Użyja/b/c
, aby wybrać pole c zagnieżdżone w polu b. - Użyj selektora podrzędnego, aby zażądać zbioru konkretnych podrzędnych pól tablic lub obiektów. W tym celu umieść wyrażenia w nawiasach
"( )"
.
Na przykład:fields=columnHeaders(name,dataType)
zwraca tylko polaname
idataType
w tablicycolumnHeaders
. Możesz też podać jedno pole podrzędne, gdziefields=columnHeader(name)
jest równoważne zfields=columnHeader/name
.
prettyPrint
prettyPrint=false
Zwraca odpowiedź w formacie zrozumiałym dla człowieka, jeśli true
.
Wartość domyślna: false
quotaUser
quotaUser=4kh4r2h4
Umożliwia egzekwowanie limitów na użytkownika w aplikacji po stronie serwera nawet w przypadku, gdy adres IP użytkownika jest nieznany. Może się tak na przykład zdarzyć w przypadku aplikacji, które w imieniu użytkownika uruchamiają zadania cron w App Engine. Możesz wybrać dowolny ciąg, który jednoznacznie identyfikuje użytkownika, ale jego długość jest ograniczona do 40 znaków.
Zastępuje ona userIp
, jeśli podano oba.
Odpowiedź
Jeśli żądanie się powiedzie, zwróci treść odpowiedzi ze strukturą JSON zdefiniowaną poniżej. Jeśli parametr output
ma wartość dataTable
, żądanie zwraca treść odpowiedzi o strukturze JSON (tabeli danych) zdefiniowanej poniżej.
Uwaga: termin „wyniki” odnosi się do całego zbioru wierszy, które pasują do zapytania, a „odpowiedź” – do zbioru wierszy zwróconych na bieżącej stronie wyników. Mogą się różnić, jeśli łączna liczba wyników jest większa niż rozmiar strony w bieżącej odpowiedzi, jak opisano w sekcji itemsPerPage.
{
"kind": "analytics#gaData",
"id": string,
"selfLink": string,
"containsSampledData": boolean,
"query": {
"start-date": string,
"end-date": string,
"ids": string,
"dimensions": [
string
],
"metrics": [
string
],
"include-empty-rows": boolean
"samplingLevel": string,
"sort": [
string
],
"filters": string,
"segment": string,
"start-index": integer,
"max-results": integer
},
"itemsPerPage": integer,
"totalResults": integer,
"previousLink": string,
"nextLink": string,
"profileInfo": {
"profileId": string,
"accountId": string,
"webPropertyId": string,
"internalWebPropertyId": string,
"profileName": string,
"tableId": string
},
"columnHeaders": [
{
"name": string,
"columnType": string,
"dataType": string
}
],
"rows": [
[
string
]
],
"sampleSize": string,
"sampleSpace": string,
"totalsForAllResults": [
{
metricName: string,
...
}
]
}
Pola odpowiedzi
Właściwości struktury treści odpowiedzi są zdefiniowane jako:
Nazwa właściwości | Wartość | Opis |
---|---|---|
kind |
string |
Typ zasobu. Wartość to „analytics#gaData”. |
id |
string |
Identyfikator tej odpowiedzi dotyczącej danych. |
query |
object |
Ten obiekt zawiera wszystkie wartości przekazywane jako parametry do zapytania. Znaczenie każdego pola zostało wyjaśnione w opisie odpowiadającego mu parametru zapytania. |
query.start-date |
string |
Data rozpoczęcia. |
query.end-date |
string |
Data zakończenia. |
query.ids |
string |
Unikalny identyfikator tabeli. |
query.dimensions[] |
list |
Lista wymiarów Analytics. |
query.metrics[] |
list |
Lista danych analitycznych. |
query.samplingLevel |
string |
Requested sampling level. |
query.include-empty-rows |
boolean |
Wartość domyślna to prawda. Jeśli ma wartość fałsz, wiersze, w których wszystkie wartości wskaźników wynoszą 0, są pomijane w odpowiedzi. |
query.sort[] |
list |
Lista danych lub wymiarów, według których dane są sortowane. |
query.filters |
string |
Rozdzielona przecinkami lista filtrów danych lub wymiarów. |
query.segment |
string |
segment Analytics. |
query.start-index |
integer |
Indeks początkowy. |
query.max-results |
integer |
Maksymalna liczba wyników na stronie. |
startIndex |
integer |
Początkowy indeks wierszy określonych przez parametr zapytania start-index . Wartość domyślna to 1. |
itemsPerPage |
integer |
Maksymalna liczba wierszy, jaką może zawierać odpowiedź, niezależnie od rzeczywistej liczby zwróconych wierszy. Jeśli jest określony parametr zapytania max-results , wartość itemsPerPage jest mniejsza z max-results lub 10 000. Wartość domyślna itemsPerPage to 1000.
|
totalResults |
integer |
Łączna liczba wierszy w wyniku zapytania niezależnie od liczby wierszy zwróconych w odpowiedzi. W przypadku zapytań, które generują dużą liczbę wierszy, totalResults może mieć wartość większą niż itemsPerPage .
Wyjaśnienie właściwości totalResults i itemsPerPage w przypadku dużych zapytań znajdziesz w sekcji Paging.
|
startDate |
string |
Data rozpoczęcia zapytania o dane określona przez parametr start-date . |
endDate |
string |
Data zakończenia dla zapytania o dane określona przez parametr end-date . |
selfLink |
string |
Link do strony z wynikami tego zapytania o dane. |
previousLink |
string |
Link do poprzedniej strony wyników dla tego zapytania o dane. |
nextLink |
string |
Link do następnej strony wyników dla tego zapytania o dane. |
profileInfo |
object |
Informacje o widoku danych (profilu), którego danych zażądano. Dane widoku (profilu) są dostępne przez interfejs Google Analytics Management API. |
profileInfo.profileId |
string |
Identyfikator widoku danych (profilu), np. 1174 . |
profileInfo.accountId |
string |
Identyfikator konta, do którego należy ten widok (profil), np. 30481 . |
profileInfo.webPropertyId |
string |
Identyfikator usługi internetowej, do której należy ten widok (profil), np. UA-30481-1 . |
profileInfo.internalWebPropertyId |
string |
Wewnętrzny identyfikator usługi internetowej, do której należy ten widok (profil), np. UA-30481-1 . |
profileInfo.profileName |
string |
Nazwa widoku (profilu). |
profileInfo.tableId |
string |
Identyfikator tabeli widoku (profile) składający się z ciągu „ga:”, po którym następuje identyfikator widoku (profilu). |
containsSampledData |
boolean |
Prawda, jeśli odpowiedź zawiera spróbkowane dane. |
sampleSize |
string |
Liczba próbek użytych do obliczenia próbkowanych danych. |
sampleSpace |
string |
Łączny rozmiar przestrzeni próbkowania. Określa całkowity dostępny rozmiar próbki, z którego zostały wybrane próbki. |
columnHeaders[] |
list |
Nagłówki kolumn zawierające nazwy wymiarów i nazwy danych. Kolejność wymiarów i danych jest taka sama jak w żądaniu określony za pomocą parametrów metrics i dimensions . Liczba nagłówków to liczba wymiarów + liczba danych. |
columnHeaders[].name |
string |
Nazwa wymiaru lub danych. |
columnHeaders[].columnType |
string |
Typ kolumny. „DIMENSION” lub „METRIC”. |
columnHeaders[].dataType |
string |
Typ danych. W nagłówkach kolumn wymiarów typ danych to tylko STRING . Nagłówki kolumn wskaźników zawierają typy danych dla wartości wskaźników, takie jak INTEGER , PERCENT , TIME , CURRENCY , FLOAT itp. Wszystkie możliwe typy danych znajdziesz w odpowiedzi interfejsu API metadanych.
|
totalsForAllResults |
object |
Łączne wartości żądanych wskaźników w postaci par klucz-wartość nazw i wartości danych. Kolejność sum wskaźników jest taka sama jak kolejność wskaźników określona w żądaniu. |
rows[] |
list |
Wiersze danych Analytics, z których każdy zawiera listę wartości wymiarów, po których następuje lista wartości danych. Kolejność wymiarów i danych jest taka sama jak w żądaniu. Każdy wiersz ma listę N pól, gdzie N = liczba wymiarów + liczba danych. |
{
"kind": "analytics#gaData",
"id": string,
"selfLink": string,
"containsSampledData": boolean,
"query": {
"start-date": string,
"end-date": string,
"ids": string,
"dimensions": [
string
],
"metrics": [
string
],
"samplingLevel": string,
"include-empty-rows": boolean,
"sort": [
string
],
"filters": string,
"segment": string,
"start-index": integer,
"max-results": integer
},
"itemsPerPage": integer,
"totalResults": integer,
"previousLink": string,
"nextLink": string,
"profileInfo": {
"profileId": string,
"accountId": string,
"webPropertyId": string,
"internalWebPropertyId": string,
"profileName": string,
"tableId": string
},
"columnHeaders": [
{
"name": string,
"columnType": string,
"dataType": string
}
],
"dataTable": {
"cols": [
{
"id": string,
"label": string,
"type": string
}
],
"rows": [
{
"c": [
{
"v": string
}
]
}
]
},
"sampleSize": string,
"sampleSpace": string,
"totalsForAllResults": [
{
metricName: string,
...
}
]
}
Pola odpowiedzi
Właściwości struktury treści odpowiedzi są zdefiniowane jako:
Nazwa właściwości | Wartość | Opis |
---|---|---|
kind |
string |
Typ zasobu. Wartość to „analytics#gaData”. |
id |
string |
Identyfikator tej odpowiedzi dotyczącej danych. |
query |
object |
Ten obiekt zawiera wszystkie wartości przekazywane jako parametry do zapytania. Znaczenie każdego pola zostało wyjaśnione w opisie odpowiadającego mu parametru zapytania. |
query.start-date |
string |
Data rozpoczęcia. |
query.end-date |
string |
Data zakończenia. |
query.ids |
string |
Unikalny identyfikator tabeli. |
query.dimensions[] |
list |
Lista wymiarów Analytics. |
query.metrics[] |
list |
Lista danych analitycznych. |
query.samplingLevel |
string |
Requested sampling level. |
query.include-empty-rows |
boolean |
Wartość domyślna to prawda. Jeśli ma wartość fałsz, wiersze, w których wszystkie wartości wskaźników wynoszą 0, są pomijane w odpowiedzi. |
query.sort[] |
list |
Lista danych lub wymiarów, według których dane są sortowane. |
query.filters |
string |
Rozdzielona przecinkami lista filtrów danych lub wymiarów. |
query.segment |
string |
segment Analytics. |
query.start-index |
integer |
Indeks początkowy. |
query.max-results |
integer |
Maksymalna liczba wyników na stronie. |
startIndex |
integer |
Początkowy indeks wierszy określonych przez parametr zapytania start-index . Wartość domyślna to 1. |
itemsPerPage |
integer |
Maksymalna liczba wierszy, jaką może zawierać odpowiedź, niezależnie od rzeczywistej liczby zwróconych wierszy. Jeśli jest określony parametr zapytania max-results , wartość itemsPerPage jest mniejsza z max-results lub 10 000. Wartość domyślna itemsPerPage to 1000.
|
totalResults |
integer |
Łączna liczba wierszy w wyniku zapytania niezależnie od liczby wierszy zwróconych w odpowiedzi. W przypadku zapytań, które generują dużą liczbę wierszy, totalResults może mieć wartość większą niż itemsPerPage .
Wyjaśnienie właściwości totalResults i itemsPerPage w przypadku dużych zapytań znajdziesz w sekcji Paging.
|
startDate |
string |
Data rozpoczęcia zapytania o dane określona przez parametr start-date . |
endDate |
string |
Data zakończenia dla zapytania o dane określona przez parametr end-date . |
selfLink |
string |
Link do strony z wynikami tego zapytania o dane. |
previousLink |
string |
Link do poprzedniej strony wyników dla tego zapytania o dane. |
nextLink |
string |
Link do następnej strony wyników dla tego zapytania o dane. |
profileInfo |
object |
Informacje o widoku danych (profilu), którego danych zażądano. Dane widoku (profilu) są dostępne przez interfejs Google Analytics Management API. |
profileInfo.profileId |
string |
Identyfikator widoku danych (profilu), np. 1174 . |
profileInfo.accountId |
string |
Identyfikator konta, do którego należy ten widok (profil), np. 30481 . |
profileInfo.webPropertyId |
string |
Identyfikator usługi internetowej, do której należy ten widok (profil), np. UA-30481-1 . |
profileInfo.internalWebPropertyId |
string |
Wewnętrzny identyfikator usługi internetowej, do której należy ten widok (profil), np. UA-30481-1 . |
profileInfo.profileName |
string |
Nazwa widoku (profilu). |
profileInfo.tableId |
string |
Identyfikator tabeli widoku (profile) składający się z ciągu „ga:”, po którym następuje identyfikator widoku (profilu). |
containsSampledData |
boolean |
Prawda, jeśli odpowiedź zawiera spróbkowane dane. |
sampleSize |
string |
Liczba próbek użytych do obliczenia próbkowanych danych. |
sampleSpace |
string |
Łączny rozmiar przestrzeni próbkowania. Określa całkowity dostępny rozmiar próbki, z którego zostały wybrane próbki. |
columnHeaders[] |
list |
Nagłówki kolumn zawierające nazwy wymiarów i nazwy danych. Kolejność wymiarów i danych jest taka sama jak w żądaniu określony za pomocą parametrów metrics i dimensions . Liczba nagłówków to liczba wymiarów + liczba danych. |
columnHeaders[].name |
string |
Nazwa wymiaru lub danych. |
columnHeaders[].columnType |
string |
Typ kolumny. „DIMENSION” lub „METRIC”. |
columnHeaders[].dataType |
string |
Typ danych. W nagłówkach kolumn wymiarów typ danych to tylko STRING . Nagłówki kolumn wskaźników zawierają typy danych dla wartości wskaźników, takie jak INTEGER , PERCENT , TIME , CURRENCY , FLOAT itp. Wszystkie możliwe typy danych znajdziesz w odpowiedzi interfejsu API metadanych.
|
totalsForAllResults |
object |
Łączne wartości żądanych wskaźników w postaci par klucz-wartość nazw i wartości danych. Kolejność sum wskaźników jest taka sama jak kolejność wskaźników określona w żądaniu. |
dataTable |
object |
Obiekt tabeli danych, którego można używać z wykresami Google. |
dataTable.cols[] |
list |
Lista deskryptorów kolumn dla wymiarów, po których występują dane. Kolejność wymiarów i danych jest taka sama jak w żądaniu za pomocą parametrów metrics i dimensions . Liczba kolumn to liczba wymiarów + liczba danych. |
dataTable.cols[].id |
string |
Identyfikator, który może służyć do odwoływania się do konkretnej kolumny (zamiast stosowania indeksów kolumn). Identyfikator wymiaru lub danych służy do ustawiania tej wartości. |
dataTable.cols[].label |
string |
Etykieta kolumny (która może być wyświetlana przez wizualizację). Identyfikator wymiaru lub danych służy do ustawiania tej wartości. |
dataTable.cols[].type |
string |
Typ danych w tej kolumnie. |
dataTable.rows[] |
list |
Wiersze danych Analytics w formacie tabeli danych, gdzie każdy wiersz jest obiektem zawierającym listę wartości komórek dla wymiarów, a po nich dane. Kolejność wymiarów i danych jest taka sama jak w żądaniu. Każda komórka zawiera listę N pól, gdzie N = liczba wymiarów + liczba danych. |
Kody błędów
Jeśli żądanie zostanie zrealizowane, interfejs API podstawowego raportowania zwraca kod stanu HTTP 200
. Jeśli podczas przetwarzania zapytania wystąpi błąd, interfejs API zwróci kod błędu i opis.
Każda aplikacja, która używa interfejsu Analytics API, musi zaimplementować odpowiednią logikę obsługi błędów. Szczegółowe informacje o kodach błędów i sposobach ich obsługi znajdziesz w
przewodniku po odpowiedziach na błędy.
Wypróbuj
Możesz wypróbować zapytania do interfejsu API podstawowego raportowania.
-
Aby wyświetlić prawidłowe kombinacje danych i wymiarów w zapytaniu, wpisz przykładowe wartości parametrów w Eksploratorze zapytań. Wyniki przykładowego zapytania są wyświetlane w postaci tabeli z wartościami wszystkich określonych danych i wymiarów.
-
Aby wysłać żądanie do aktywnych danych i zobaczyć odpowiedź w formacie JSON, wypróbuj metodę
analytics.data.ga.get
w Eksploratorze interfejsów API danych Google.
Próbkowanie
Google Analytics oblicza określone kombinacje wymiarów i danych na bieżąco. Aby zwrócić dane w rozsądnym czasie, Google Analytics może przetworzyć tylko próbkę danych.
Aby określić poziom próbkowania dla żądania, możesz ustawić parametr samplingLevel.
Jeśli odpowiedź interfejsu API podstawowego raportowania zawiera próbkowane dane, pole odpowiedzi containsSampledData
będzie miało wartość true
.
Dodatkowo 2 właściwości będą podawać informacje o poziomie próbkowania dla zapytania: sampleSize
i sampleSpace
.
Za pomocą tych 2 wartości możesz obliczyć odsetek sesji użytych dla danego zapytania. Jeśli np.sampleSize
to 201,000
, a sampleSpace
to 220,000
,raport zostanie wygenerowany na podstawie (201 000 / 220 000) * 100 = 91,36% sesji.
Ogólny opis próbkowania i jego zastosowania w Google Analytics znajdziesz w sekcji Próbkowanie.
Obsługa wyników z dużymi danymi
Jeśli spodziewasz się, że zapytanie zwróci duży zbiór wyników, skorzystaj z poniższych wskazówek, które pomogą Ci zoptymalizować zapytanie do interfejsu API, uniknąć błędów i zminimalizować przypadki przekroczenia limitu. Pamiętaj, że wyznaczamy punkt odniesienia dla wydajności, zezwalając na maksymalnie 7 wymiarów i 10 wskaźników na jedno żądanie do interfejsu API. Chociaż przetwarzanie niektórych zapytań, które określają dużą liczbę danych i wymiarów, może trwać dłużej niż innych, ograniczenie liczby żądanych danych może nie wystarczyć do zwiększenia wydajności zapytań. Aby uzyskać najlepszą wydajność, możesz stosować poniższe metody.
Zmniejszanie wymiarów na zapytanie
Interfejs API umożliwia określenie do 7 wymiarów w jednym żądaniu. Google Analytics często musi na bieżąco obliczać wyniki tych złożonych zapytań. Może to być szczególnie czasochłonne, jeśli liczba wynikowych wierszy jest duża. Na przykład zapytanie o słowa kluczowe według miast i godzin może odpowiadać milionom wierszy danych. Aby poprawić wydajność, zmniejsz liczbę wierszy przetwarzanych przez Google Analytics przez ograniczenie liczby wymiarów w zapytaniu.
Podział zapytania według zakresu dat
Zamiast stronicować wyniki z jednym długim zakresem dat jako kluczem, rozważ tworzenie osobnych zapytań dla jednego tygodnia lub nawet jednego dnia. W przypadku dużego zbioru danych nawet żądanie danych z jednego dnia może zwrócić więcej niż max-results
i w takim przypadku nie da się uniknąć stronicowania. Jeśli jednak liczba wierszy zgodnych z zapytaniem przekracza max-results
, rozdzielenie zakresu dat może skrócić łączny czas potrzebny na pobranie wyników. To podejście może zwiększyć wydajność zarówno w przypadku zapytań jednowątkowych, jak i równoległych.
Paging
Podział wyników na strony może być dobrym sposobem na podzielenie dużych zbiorów wyników na łatwe do ogarnięcia części. Pole totalResults
informuje o liczbie pasujących wierszy, a itemsPerPage
podaje maksymalną liczbę wierszy, które mogą zostać zwrócone w wyniku.
Jeśli stosunek totalResults
do itemsPerPage
jest wysoki, realizacja poszczególnych zapytań może trwać dłużej, niż jest to konieczne. Jeśli potrzebujesz tylko ograniczonej liczby wierszy – na przykład do wyświetlania, wygodniejsze może być ustawienie wyraźnego limitu rozmiaru odpowiedzi za pomocą parametru max-results
. Jeśli jednak Twoja aplikacja musi przetworzyć duży zbiór wyników w całości, wydajniejsze może być żądanie maksymalnej dozwolonej liczby wierszy.
Korzystanie z gzip
Kompresja gzip pozwala łatwo i wygodnie zmniejszyć przepustowość potrzebną do obsługi żądań. Choć zdekompresowanie wyników wymaga dodatkowego czasu procesora, to kompresja kosztów sieci sprawia, że jest to zwykle bardzo korzystne. Aby odebrać odpowiedź zakodowaną w formacie gzip, ustaw nagłówek Accept-Encoding
i dodaj do klienta użytkownika ciąg znaków gzip
.
Oto przykład prawidłowo sformatowanych nagłówków HTTP, które umożliwiają włączenie kompresji gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)