Core Reporting API – przewodnik

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:
  • 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.
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
To pole jest wymagane.
Unikalny identyfikator służący do pobierania danych Analytics. Ten identyfikator jest połączeniem przestrzeni nazw 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
To pole jest wymagane.
Wszystkie żądania danych Analytics muszą mieć określony zakres dat. Jeśli w żądaniu nie podasz parametrów 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.
Daty względne zawsze odnoszą się do bieżącej daty w momencie wykonywania zapytania i zależą od strefy czasowej widoku (profilu) określonego w zapytaniu.

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
To pole jest wymagane.
Wszystkie żądania danych Analytics muszą mieć określony zakres dat. Jeśli w żądaniu nie podasz parametrów 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).
Najwcześniejsza prawidłowa wartość end-date to 2005-01-01. end-date nie ma górnego limitu.
Daty względne zawsze odnoszą się do bieżącej daty w momencie wykonywania zapytania i zależą od strefy czasowej widoku (profilu) określonego w zapytaniu.

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
Opcjonalnie.
Parametr 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
To pole jest wymagane.
Zbiorcze statystyki aktywności użytkowników w Twojej witrynie, np. kliknięć czy odsłon. Jeśli zapytanie nie ma parametru 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
Opcjonalnie.

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 lub metrics. 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
  1. Składnia filtra
  2. Operatory filtrowania
  3. Filtry wyrażeń
  4. Łączenie filtrów
Opcjonalnie.

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.

Filtry wskaźników
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

Filtry wymiarów
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 \,
  • 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.

Łą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

I

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
Opcjonalnie.

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
Opcjonalnie.
Użyj tego parametru, aby ustawić poziom próbkowania (tj. liczbę sesji używanych do obliczenia wyniku) dla zapytania raportowania. Dozwolone wartości są spójne z interfejsem internetowym i obejmują:
  • 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.
Jeśli nie zostanie podany, używany jest poziom próbkowania DEFAULT.
Szczegółowe informacje o tym, jak obliczyć odsetek sesji użytych w przypadku zapytania, znajdziesz w sekcji Próbkowanie.

uwzględnij-puste-wiersze

include-empty-rows=true
Opcjonalnie.
Wartość domyślna to prawda. Jeśli ustawisz wartość fałsz, wiersze, w których wszystkie wartości wskaźników wynoszą 0, będą pomijane w odpowiedzi. Jeśli np. w zapytaniu uwzględnisz więcej niż 1 rodzaj danych, wiersze zostaną usunięte tylko wtedy, gdy wszystkie wartości danych będą wynosić 0. Jest to przydatne, gdy tworzysz żądanie, w którym liczba prawidłowych wierszy jest znacznie mniejsza niż liczba oczekiwanych wartości wymiarów.

start-index

start-index=10
Opcjonalnie.
Jeśli nie zostanie podany, indeks początkowy to 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
Opcjonalnie.
Maksymalna liczba wierszy do uwzględnienia w tej odpowiedzi. Możesz go używać w połączeniu z funkcją 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.
Interfejs Analytics Core Reporting API zwraca maksymalnie 10 000 wierszy na żądanie,niezależnie od tego, ile zażądasz. Jeśli nie ma oczekiwanej liczby segmentów wymiarów, liczba wierszy może być mniejsza od żądanej. Na przykład w polu 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
Opcjonalnie.
Użyj tego parametru, aby ustawić typ wyjściowy danych Analytics zwracanych w odpowiedzi. Dozwolone wartości:
  • 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). Obiektu Data Table można używać bezpośrednio z wizualizacjami Map Google.
Jeśli nie zostanie podana, zostanie użyta domyślna odpowiedź JSON.

pola

fields=rows,columnHeaders(name,dataType)
Opcjonalnie.

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żyj a/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 pola name i dataType w tablicy columnHeaders. Możesz też podać jedno pole podrzędne, gdzie fields=columnHeader(name) jest równoważne z fields=columnHeader/name.

prettyPrint

prettyPrint=false
Opcjonalnie.

Zwraca odpowiedź w formacie zrozumiałym dla człowieka, jeśli true. Wartość domyślna: false

quotaUser

quotaUser=4kh4r2h4
Opcjonalnie.

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.

JSON
{
  "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.
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.
JSON (tabela 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.
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)