Core Reporting API – przewodnik informacyjny

Ten dokument zawiera pełne odniesienie do zapytania i odpowiedzi w przypadku interfejsu Core Reporting API w wersji 3.0.

Wprowadzenie

Wysyłasz zapytania dotyczące danych raportu dotyczącego podstawowego interfejsu API do raportowania w Google Analytics. Każde zapytanie wymaga identyfikatora (profilu) wyświetlenia, daty rozpoczęcia i zakończenia oraz co najmniej 1 rodzaju danych. Możesz też podać dodatkowe parametry zapytania, takie jak wymiary, filtry i segmenty, aby zawęzić zapytanie. Informacje o współdziałaniu tych koncepcji znajdziesz w przewodniku.

Żądanie

Interfejs API udostępnia jedną metodę przesyłania danych:

analytics.data.ga.get()

Ta metoda jest widoczna w różnych bibliotekach klienta i ma interfejsy API odpowiednie do ustawiania parametrów zapytania.

Zapytanie do interfejsu API można też wykonać jako punkt końcowy 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 adresu URL określa parametr zapytania API, który musi być zakodowany na potrzeby adresu URL.

Podsumowanie parametrów zapytań

W tabeli poniżej znajdziesz wszystkie parametry zapytań akceptowane przez interfejs Core Reporting API. Kliknij nazwę każdego parametru, by zobaczyć szczegółowy opis.

Nazwa Wartość Wymagany Podsumowanie
ids string Tak Unikalny identyfikator tabeli w formacie ga:XXXX, gdzie XXXX to identyfikator widoku danych (profil) Analytics, dla którego zapytanie pobierze dane.
start-date string Tak Data rozpoczęcia pobierania danych Analytics. Żądania mogą zawierać datę rozpoczęcia w formacie YYYY-MM-DD lub jako względną (np. today, yesterday lub NdaysAgo, gdzie N jest dodatnią liczbą całkowitą.
end-date string Tak Data zakończenia pobierania danych Analytics. Żądanie może określać datę zakończenia w formacie YYYY-MM-DD lub jako względną (np. today, yesterday lub NdaysAgo, gdzie N jest dodatnią liczbą całkowitą.
metrics string Tak Lista danych rozdzielonych przecinkami, np. ga:sessions,ga:bounces.
dimensions string nie Lista rozdzielonych przecinkami wymiarów danych 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ą dane zwracane na potrzeby żądania.
segment string nie Segmenty przeznaczone do danych zwróconych dla Twojego żądania.
samplingLevel string nie Żądany poziom próbkowania. Dozwolone wartości:
  • DEFAULT – zwraca odpowiedź z przykładowym rozmiarem, który równoważy szybkość i dokładność.
  • FASTER – zwraca szybką odpowiedź z mniejszym rozmiarem próbki.
  • HIGHER_PRECISION – zwraca dokładniejszą odpowiedź z wykorzystaniem dużego rozmiaru próbki, ale może to spowodować spowolnienie odpowiedzi.
include-empty-rows boolean nie Domyślnie ma wartość Prawda. Jeśli ma wartość Fałsz, wiersze, w których wszystkie wartości danych wynoszą zero, są pomijane.
start-index integer nie Pierwszy wiersz danych do pobrania, począwszy od 1. Używaj tego parametru jako mechanizmu podziału na strony wraz z parametrem max-results.
max-results integer nie Maksymalna liczba wierszy do uwzględnienia w odpowiedzi.
output string nie Typ danych wyjściowych, których dotyczą dane zwracane w odpowiedzi w Analytics. Dopuszczalne wartości to json i dataTable. Domyślnie: json.
fields string nie Selektor określający podzbiór pól do uwzględnienia w odpowiedzi.
prettyPrint string nie Zwraca odpowiedź z wcięciem 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 limitu wykorzystania na adres IP.
quotaUser string nie Alternatywa dla identyfikatora User-ID w sytuacji, gdy adres IP użytkownika jest nieznany.
access_token string nie Jednym ze sposobów dostarczania tokena OAuth 2.0.
callback string nie Nazwa funkcji wywołania zwrotnego JavaScriptu, która obsługuje odpowiedź. Używana w żądaniach JSON-P JavaScriptu.
key string nie Służy do autoryzacji OAuth 1.0, by określić aplikację, w której chcesz uzyskać limit. Na przykład: key=AldefliuhSFADSfasdfasdfASdf.

Szczegóły parametru zapytania

identyfikatory

ids=ga:12345
Wymagany.
Unikalny identyfikator służący do pobierania danych Analytics. Ten identyfikator jest połączeniem przestrzeni nazw ga: z identyfikatorem widoku danych (profilu). Identyfikator widoku danych możesz pobrać, korzystając z metody analytics.management.profiles.list, która udostępnia właściwość id w zasobie View (Profil) w interfejsie Google Analytics Management API.

Data rozpoczęcia

start-date=2009-04-20
Wymagany.
Wszystkie żądania danych Analytics muszą mieć zakres dat. Jeśli żądanie nie zawiera parametrów start-date i end-date, serwer zwraca błąd. Wartości dat mogą dotyczyć konkretnej daty. Można to zrobić za pomocą wzorca YYYY-MM-DD lub względnego, używając wzorca today, yesterday lub wzorca NdaysAgo. Wartości muszą być zgodne z: [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).
Najwcześniejsza prawidłowa wartość start-date to 2005-01-01. W przypadku daty rozpoczęcia nie ma górnego limitu.
Daty względne są zawsze zgodne z bieżącą datą w momencie zapytania i zależą od strefy czasowej widoku (profilu) określonego w zapytaniu.

Przykładowy zakres dat z ostatnich 7 dni (od wczoraj) z wykorzystaniem dat względnych:

  &start-date=7daysAgo
  &end-date=yesterday

data zakończenia

end-date=2009-05-20
Wymagany.
Wszystkie żądania danych Analytics muszą mieć zakres dat. Jeśli żądanie nie zawiera parametrów start-date i end-date, serwer zwraca błąd. Wartości dat mogą dotyczyć konkretnej daty. Można to zrobić za pomocą wzorca YYYY-MM-DD lub względnego, używając wzorca today, yesterday lub wzorca NdaysAgo. Wartości muszą być zgodne z: [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. W przypadku właściwości end-date nie ma górnego limitu.
Daty względne są zawsze zgodne z bieżącą datą w momencie zapytania i zależą od strefy czasowej widoku (profilu) określonego w zapytaniu.

Przykładowy zakres dat z ostatnich 10 dni (od dzisiaj) przy użyciu dat względnych:

  &start-date=9daysAgo
  &end-date=today

wymiary

dimensions=ga:browser,ga:city
Opcjonalne.
Parametr dimensions dzieli dane według wspólnych kryteriów, na przykład według parametru ga:browser lub ga:city. Chociaż możesz poprosić o łączną liczbę odsłon Twojej witryny, ciekawsza może być liczba wyświetleń w podziale na przeglądarki. W takim przypadku zobaczysz liczbę odsłon z Firefoksa, Internet Explorera, Chrome itd.

Jeśli używasz w żądaniu danych tagu dimensions, pamiętaj o tych ograniczeniach:

  • W każdym zapytaniu możesz podać maksymalnie 7 wymiarów.
  • Nie możesz wysyłać zapytania składającego się tylko z wymiarów. Należy połączyć wszystkie żądane wymiary z co najmniej 1 rodzajem danych.
  • W tym samym zapytaniu można wysyłać zapytania tylko o niektóre wymiary. Skorzystaj z prawidłowego narzędzia do łączenia w Wymiarach i danych, aby sprawdzić, których wymiarów można używać razem.


wskaźnika

metrics=ga:sessions,ga:bounces
Wymagany.
Zbiorcze statystyki aktywności użytkowników strony, np. kliknięć czy odsłon. Jeśli zapytanie nie zawiera parametru dimensions, zwrócone dane zawierają zbiorcze wartości dla wybranego zakresu dat, np. łączną liczbę odsłon lub łączną liczbę odrzuceń. Jeśli jednak żądane są wymiary, wartości są podzielone na segmenty według wartości wymiaru. Na przykład wartość ga:pageviews wymagana w polu ga:country zwraca łączną liczbę odsłon w poszczególnych krajach. Żądając statystyk, pamiętaj o tych kwestiach:
  • Każde żądanie musi zawierać co najmniej 1 rodzaj danych. Żądanie nie może zawierać tylko wymiarów.
  • Dla każdego zapytania możesz podać maksymalnie 10 rodzajów danych.
  • Większość kombinacji danych z wielu kategorii może być używana razem, pod warunkiem, że nie określono żadnych wymiarów.
  • Danych można używać w połączeniu z innymi wymiarami lub danymi, ale tylko wtedy, gdy pasujące dane są stosowane. Więcej informacji znajdziesz w opisie wymiarów i danych.


sortuj

sort=ga:country,ga:browser
Opcjonalne.

Lista wskaźników i wymiarów wskazujących kolejność sortowania i kierunek sortowania zwracanych danych.

  • Sortowanie kolejności jest określane od lewej do prawej strony wymienionych wskaźników i wymiarów.
  • Domyślnie sortowanie w kierunku jest rosnąco i można je zmienić na malejąco, używając znaku minusa (-) w odpowiednim polu.

Dzięki sortowaniu wyników zapytania możesz zadawać różne pytania dotyczące swoich danych. Na przykład w odpowiedzi na pytanie „Jakich krajów używam najczęściej i w których przeglądarkach najczęściej korzystają??”? możesz wysłać zapytanie opisane poniżej. Kolumna sortuje się najpierw według kolumny ga:country, a następnie ga:browser według kolejności rosnącej:

sort=ga:country,ga:browser

Odpowiedz na powiązane pytanie i sprawdź, które przeglądarki są najczęściej używane i w których krajach najczęściej ich używasz. Możesz utworzyć zapytanie, używając tego parametru: Kolumna sortuje się najpierw według kolumny ga:browser, a następnie ga:country według kolejności rosnącej:
sort=ga:browser,ga:country

Korzystając z parametru sort, pamiętaj o tych kwestiach:

  • Możesz je sortować tylko według wartości wymiarów lub danych użytych w parametrach dimensions lub metrics. Jeśli żądanie zostanie posortowane według pola, które nie jest określone w parametrze ani wymiarach, zostaną wyświetlone błędy.
  • Domyślnie ciągi są sortowane w kolejności rosnącej według alfabetu en-US.
  • Numery są domyślnie sortowane w kolejności rosnącej.
  • Domyślnie daty są sortowane w kolejności rosnącej według daty.

filtry

filters=ga:medium%3D%3Dreferral
Opcjonalne.

Parametr ciągu zapytania filters ogranicza dane zwracane w żądaniu. Aby użyć parametru filters, podaj wymiar lub dane, według których chcesz filtrować, a potem wyrażenie filtra. Na przykład następujące zapytanie zażąda ga:pageviews i ga:browser w widoku (profil) 12134, gdzie wymiar ga:browser zaczyna się ciągiem znaków 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

Filtrowane zapytania ograniczają liczbę wierszy, które zawierają (lub nie) są uwzględniane w wyniku. Każdy wiersz wyniku jest porównywany z filtrem: jeśli filtr do niego pasuje, zostaje zachowany, a jeśli nie pasuje, wiersz zostaje usunięty.

  • Kodowanie adresów URL: biblioteki klienta interfejsu API Google automatycznie kodują operatory filtrowania.
  • Filtrowanie wymiarów: filtrowanie odbywa się przed dowolnym wymiarem, więc zwrócone dane dotyczą tylko odpowiednich wymiarów. W przykładzie powyżej liczba odsłon będzie wskazywać tylko wyświetlenia strony, w których przeglądarka Firefox jest wyłączona.
  • Filtrowanie danych: filtrowanie danych odbywa się po agregowaniu danych.
  • Prawidłowe kombinacje: możesz filtrować według wymiaru lub danych, które nie są częścią zapytania, pod warunkiem, że wszystkie wymiary lub dane w żądaniu oraz filtr są prawidłowymi kombinacjami. Możesz na przykład wysłać zapytanie o datę listy odsłon, która jest filtrowana w określonej przeglądarce. Więcej informacji znajdziesz w opisie wymiarów i danych.

Składnia filtra


Jeden filtr używa formularza:

ga:name operator expression

W tej składni:

  • name – nazwa wymiaru lub rodzaju danych, według których chcesz filtrować dane. Na przykład: ga:pageviews filtruje dane o odsłonach.
  • Operator – określa typ dopasowania filtra, którego należy użyć. Operatory odnoszą się do wymiarów lub danych.
  • wyrażenie – określa wartości, które mają zostać uwzględnione w wynikach lub z nich wykluczone. Wyrażenia korzystają ze składni wyrażeń regularnych.

Filtruj operatorów


Istnieje 6 operatorów filtrowania dla wymiarów i 6 filtrów na wskaźniki. Aby operatory były uwzględniane w ciągach zapytania adresu URL, muszą być zakodowane na potrzeby adresu URL.

Wskazówka: użyj eksploratora zapytań do pliku danych, aby zaprojektować filtry wymagające kodowania adresów URL, ponieważ eksplorator zapytań automatycznie koduje adresy URL zawierające ciągi znaków i spacje.

Filtry wskaźników
Operator Opis Formularz zakodowany na potrzeby adresu URL Przykłady
== Równe %3D%3D Wyświetl wyniki, gdy czas na stronie wynosi dokładnie 10 sekund:
filters=ga:timeOnPage%3D%3D10
!= Różne od !%3D Wyświetl wyniki, gdy czas na stronie nie wynosi 10 sekund:
filters=ga:timeOnPage!%3D10
> Większe niż %3E Zwróć wyniki, gdy czas na stronie przekracza 10 sekund:
filters=ga:timeOnPage%3E10
< Mniejsze niż %3C Zwracanie wyników, gdy czas na stronie jest krótszy niż 10 sekund:
filters=ga:timeOnPage%3C10
>= Ma wartość większą lub równą %3E%3D Wyświetl wyniki, gdy czas na stronie wynosi co najmniej 10 sekund:
filters=ga:timeOnPage%3E%3D10
<= Ma wartość mniejszą lub równą %3C%3D Wyświetl wyniki, gdy czas na stronie wynosi maksymalnie 10 sekund:
filters=ga:timeOnPage%3C%3D10

Filtry wymiarów
Operator Opis Formularz zakodowany na potrzeby adresu URL Przykład
== Dopasowanie ścisłe %3D%3D Dane zbiorcze, w których miasto to Irvine:
filters=ga:city%3D%3DIrvine
!= Nie pasuje !%3D Dane zbiorcze, w których miasto nie jest Irvine:
filters=ga:city!%3DIrvine
=@ Zawiera podłańcuch %3D@ Dane zbiorcze, w których miasto zawiera Jork:
filters=ga:city%3D@York
!@ Nie zawiera podłańcucha !@ Dane zbiorcze, gdy miasto nie zawiera Jorku:
filters=ga:city!@York
=~ Zawiera dopasowanie do wyrażenia regularnego %3D~ Dane zbiorcze, w których miasto zaczyna się od Nowe:

filters=ga:city%3D~%5ENew.* (%5E to adres URL zakodowany na podstawie znaku ^, który zakotwicza wzorzec na początku ciągu znaków).
!~ Brak dopasowania do wyrażenia regularnego !~ Dane zbiorcze, w przypadku których miasto nie zaczyna się od Nowe:
filters=ga:city!~%5ENew.*

Filtruj wyrażenia

Jest kilka ważnych reguł dotyczących wyrażeń filtra:

  • Znaki zarezerwowane dla adresów URL – znaki takie jak & muszą być zakodowane na potrzeby adresu URL w zwykły sposób.
  • Zastrzeżone znaki – średnik i przecinek muszą być poprzedzone znakiem ukośnikiem lewym, jeśli występują w wyrażeniu:
    • średnik \;
    • przecinek \,
  • Wyrażenia regularne – możesz też używać wyrażeń regularnych w operatorach filtrów za pomocą operatorów =~ i !~. Ich składnia jest podobna do wyrażenia regularnego Perl i ma te dodatkowe reguły:
    • Maksymalna długość 128 znaków – w przypadku wyrażeń dłuższych niż 128 znaków zwracany jest kod stanu 400 Bad Request.
    • Wielkość liter – wielkość liter nie jest rozróżniana.

Łączenie filtrów

Filtry można łączyć, korzystając z logiki logicznej OR i AND. Pozwala to skutecznie zwiększyć limit 128 znaków w wyrażenie filtra.

LUB

Operator OR jest określany za pomocą przecinka (,). Ma 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 albo (Stany Zjednoczone LUB Kanada):
ga:country==United%20States,ga:country==Canada

Użytkownicy przeglądarki Firefox w systemach operacyjnych (Windows i macOS):
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

ORAZ

Operator AND jest definiowany przez średnik (;). Przed nim znajduje się operator OR i można go użyć do połą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 'pl':
ga:country==United%20States;ga:language!~^en.*

System operacyjny to (Windows macOS) lub 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
Opcjonalne.

Szczegółowe informacje o tym, jak zażądać segmentu w interfejsie Core Reporting API, znajdziesz w Przewodniku po tworzeniu segmentów.

Koncepcyjne informacje o segmentach znajdziesz w artykułach Informacje o funkcjach segmentów i Segmenty w Centrum pomocy.

Wymiary i dane dozwolone w segmentach
Nie wszystkie wymiary i dane mogą być używane w segmentach. Aby sprawdzić, które wymiary i dane są dozwolone w segmentach, otwórz Eksplorator wymiarów i danych.


Poziom próbkowania

samplingLevel=DEFAULT
Opcjonalne.
Użyj tego parametru, aby ustawić poziom próbkowania (tj. liczbę sesji użytych do obliczenia wyniku) dla zapytania raportowania. Dozwolone wartości są zgodne z interfejsem internetowym i obejmują:
  • DEFAULT – zwraca odpowiedź z przykładowym rozmiarem, który równoważy szybkość i dokładność.
  • FASTER – zwraca szybką odpowiedź z mniejszym rozmiarem próbki.
  • HIGHER_PRECISION – zwraca dokładniejszą odpowiedź z wykorzystaniem dużego rozmiaru próbki, ale może to spowodować spowolnienie odpowiedzi.
Jeśli wartość nie zostanie podana, zostanie użyty poziom próbkowania DEFAULT.
Szczegółowe informacje o obliczaniu odsetka sesji użytych w zapytaniu znajdziesz w sekcji Dobór próby.

uwzględnij puste wiersze

include-empty-rows=true
Opcjonalne.
Domyślnie ma wartość Prawda. Jeśli ma wartość Fałsz, wiersze, w których wszystkie wartości danych wynoszą zero, są pomijane. Jeśli na przykład dodasz do zapytania więcej niż 1 rodzaj danych, wiersze zostaną usunięte tylko wtedy, gdy wszystkie wartości tych danych będą wynosić 0. Może to być przydatne, gdy spodziewasz się, że liczba prawidłowych wierszy jest mniejsza niż liczba oczekiwanych wartości wymiarów.

indeks-początkowy

start-index=10
Opcjonalne.
Jeśli nie zostanie podany, indeks początkowy to 1. (Indeksy wyników są zależne od 1. Oznacza to, że pierwszy wiersz to wiersz 1, a nie 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 pobrać wiersze zindeksowane jako liczba 10 001 i później.

wyniki-maksymalne

max-results=100
Opcjonalne.
Maksymalna liczba wierszy w tej odpowiedzi. Możesz użyć tej właściwości w połączeniu z metodą start-index, aby pobrać podzbiór elementów, lub użyć jej tylko do ograniczenia liczby zwracanych elementów, począwszy od pierwszego. Jeśli nie podasz właściwości max-results, zapytanie zwróci domyślną maksymalną liczbę 1000 wierszy.
Interfejs Analytics Core Reporting API zwraca maksymalnie 10 tys. wierszy na żądanie, niezależnie od liczby próśb o nie. Jeśli nie ma oczekiwanej liczby segmentów wymiarów, może ona zwracać mniej wierszy niż wymagana. Na przykład w przypadku właściwości ga:country dostępnych jest mniej niż 300 wartości, więc segmentując dane tylko według kraju, nie możesz przekroczyć 300 wierszy, nawet jeśli max-results ma większą wartość.

wynik

output=dataTable
Opcjonalne.
Użyj tego parametru, aby ustawić typ wyjściowy danych Analytics zwracanych w odpowiedzi. Dozwolone wartości to:
  • json – zapisuje w odpowiedzi domyślną właściwość rows zawierającą obiekt JSON.
  • dataTable – powoduje wysłanie w odpowiedzi właściwości dataTable zawierającej obiekt Tabela danych. Tego obiektu Data Table można używać bezpośrednio z wizualizacjami Wykresów Google.
Jeśli nie zostanie podany, zostanie użyta domyślna odpowiedź JSON.

pola

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

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, za pomocą parametru fields możesz określić, które pola chcesz uwzględnić.

Format wartości parametru żądania jest luźno oparty na składni XPath. Obsługiwane składni zostały opisane poniżej.

  • Aby wybrać wiele pól, użyj listy rozdzielonej przecinkami.
  • Użyj 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 pól podrzędnych tablic lub obiektów, umieszczając wyrażenia w nawiasach "( )".
    Na przykład: fields=columnHeaders(name,dataType) zwraca tylko pola name i dataType w tablicy columnHeaders. Możesz też określić jedno pole podrzędne, gdzie fields=columnHeader(name) jest odpowiednikiem fields=columnHeader/name.

FairPrint

prettyPrint=false
Opcjonalne.

Zwraca odpowiedź w formacie zrozumiałym dla użytkownika, jeśli jest to true. Wartość domyślna: false


limitUżytkownika

quotaUser=4kh4r2h4
Opcjonalne.

Pozwala wymuszać stosowanie limitów na użytkownika z aplikacji po stronie serwera, nawet jeśli adres IP użytkownika jest nieznany. Może to na przykład dotyczyć aplikacji, które uruchamiają zadania cron w App Engine w imieniu użytkownika. Możesz wybrać dowolny ciąg znaków, który jednoznacznie identyfikuje użytkownika, ale jego długość jest ograniczona do 40 znaków.

Ta wartość zastępuje userIp, jeśli obie zostaną podane.


Odpowiedź

Jeśli operacja się uda, żądanie zwróci treść odpowiedzi ze strukturą JSON zdefiniowaną poniżej. Jeśli parametr output ma wartość dataTable, żądanie zwraca treść odpowiedzi o zdefiniowanej poniżej strukturze JSON (tabeli danych).

Uwaga: termin "results" odnosi się do całego zestawu wierszy pasujących do zapytania, a &"response" odnosi się do zestawu wierszy zwróconych na bieżącej stronie wyników. Te wyniki mogą się różnić, jeśli łączna liczba wyników jest większa niż rozmiar strony dla 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 odpowiedzi są zdefiniowane w następujący sposób:

Nazwa usługi Wartość Opis
kind string Typ zasobu. Wartość to "analytics#gaData".
id string Identyfikator tej odpowiedzi na dane.
query object Ten obiekt zawiera wszystkie wartości przekazane jako parametry zapytania. Znaczenie każdego pola znajdziesz 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 Domyślnie ma wartość Prawda. Jeśli ma wartość Fałsz, wiersze, w których wszystkie wartości danych wynoszą zero, są pomijane.
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 Uruchom indeks.
query.max-results integer Maksymalna liczba wyników na stronie.
startIndex integer Początkowy indeks wierszy określony przez parametr zapytania start-index. Wartość domyślna to 1.
itemsPerPage integer Maksymalna liczba wierszy, które może zawierać odpowiedź, niezależnie od rzeczywistej liczby zwróconych wierszy. Jeśli podasz parametr zapytania max-results, wartość itemsPerPage będzie mniejsza niż max-results lub 10 000. Wartością domyślną jest itemsPerPage.
totalResults integer Łączna liczba wierszy w wyniku zapytania niezależnie od liczby wierszy zwróconych w odpowiedzi. W przypadku zapytań, które skutkują dużą liczbą wierszy, wartość totalResults może być większa niż itemsPerPage. Więcej informacji o totalResults i itemsPerPage znajdziesz w przypadku dużych zapytań – Pag.
startDate string Data rozpoczęcia zapytania o dane określona przez parametr start-date.
endDate string Data zakończenia zapytania o dane określona przez parametr end-date.
profileInfo object Informacje o widoku (profilu), którego dotyczy żądanie danych. Dane o profilach są dostępne za pomocą interfejsu Google Analytics Management API.
profileInfo.profileId string Identyfikator profilu (np. 1174).
profileInfo.accountId string Identyfikator konta, do którego należy ten widok (np. 30481).
profileInfo.webPropertyId string Identyfikator usługi internetowej, do której należy ten widok (np. UA-30481-1).
profileInfo.internalWebPropertyId string Wewnętrzny identyfikator usługi internetowej, do której należy ten widok (np. UA-30481-1).
profileInfo.profileName string Nazwa widoku danych (profilu).
profileInfo.tableId string Identyfikator tabeli dla (widoku) profilu, złożony z ciągu "ga:" po którym następuje identyfikator widoku danych (profilu).
containsSampledData boolean Wartość „prawda”, jeśli odpowiedź zawiera próbkowane dane.
sampleSize string Liczba próbek używanych do obliczania danych próbkowanych.
sampleSpace string Łączny rozmiar miejsca próbkowania. Ta wartość 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 wraz z nazwami danych. Kolejność wymiarów i danych jest taka sama jak określona w żądaniu za pomocą parametrów metrics i dimensions. Liczba nagłówków to liczba wymiarów + liczba danych.
columnHeaders[].name string Nazwa wymiaru lub rodzaju danych.
columnHeaders[].columnType string Typ kolumny. "wymiar" &"METRIC&&tt.
columnHeaders[].dataType string Typ danych. Typ nagłówka danych w kolumnie wymiaru to STRING. Nagłówki kolumn danych zawierają typy danych dla takich wartości jak INTEGER, PERCENT, TIME, CURRENCY, FLOAT itd. Wszystkie możliwe typy danych znajdziesz w odpowiedzi interfejsu API metadanych.
totalsForAllResults object Łączna wartość dla żądanych wskaźników w postaci par klucz-wartość nazw i wartości. Kolejność tabel wskaźników jest taka sama jak kolejność wskaźników w żądaniu.
rows[] list Wiersze danych Analytics, w których każdy wiersz zawiera listę wartości wymiaru wraz z wartościami danych. Kolejność wymiarów i danych jest taka sama jak określona w żądaniu. Każdy wiersz zawiera listę N pól, w których 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 odpowiedzi są zdefiniowane w następujący sposób:

Nazwa usługi Wartość Opis
kind string Typ zasobu. Wartość to "analytics#gaData".
id string Identyfikator tej odpowiedzi na dane.
query object Ten obiekt zawiera wszystkie wartości przekazane jako parametry zapytania. Znaczenie każdego pola znajdziesz 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 Domyślnie ma wartość Prawda. Jeśli ma wartość Fałsz, wiersze, w których wszystkie wartości danych wynoszą zero, są pomijane.
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 Uruchom indeks.
query.max-results integer Maksymalna liczba wyników na stronie.
startIndex integer Początkowy indeks wierszy określony przez parametr zapytania start-index. Wartość domyślna to 1.
itemsPerPage integer Maksymalna liczba wierszy, które może zawierać odpowiedź, niezależnie od rzeczywistej liczby zwróconych wierszy. Jeśli podasz parametr zapytania max-results, wartość itemsPerPage będzie mniejsza niż max-results lub 10 000. Wartością domyślną jest itemsPerPage.
totalResults integer Łączna liczba wierszy w wyniku zapytania niezależnie od liczby wierszy zwróconych w odpowiedzi. W przypadku zapytań, które skutkują dużą liczbą wierszy, wartość totalResults może być większa niż itemsPerPage. Więcej informacji o totalResults i itemsPerPage znajdziesz w przypadku dużych zapytań – Pag.
startDate string Data rozpoczęcia zapytania o dane określona przez parametr start-date.
endDate string Data zakończenia zapytania o dane określona przez parametr end-date.
profileInfo object Informacje o widoku (profilu), którego dotyczy żądanie danych. Dane o profilach są dostępne za pomocą interfejsu Google Analytics Management API.
profileInfo.profileId string Identyfikator profilu (np. 1174).
profileInfo.accountId string Identyfikator konta, do którego należy ten widok (np. 30481).
profileInfo.webPropertyId string Identyfikator usługi internetowej, do której należy ten widok (np. UA-30481-1).
profileInfo.internalWebPropertyId string Wewnętrzny identyfikator usługi internetowej, do której należy ten widok (np. UA-30481-1).
profileInfo.profileName string Nazwa widoku danych (profilu).
profileInfo.tableId string Identyfikator tabeli dla (widoku) profilu, złożony z ciągu "ga:" po którym następuje identyfikator widoku danych (profilu).
containsSampledData boolean Wartość „prawda”, jeśli odpowiedź zawiera próbkowane dane.
sampleSize string Liczba próbek używanych do obliczania danych próbkowanych.
sampleSpace string Łączny rozmiar miejsca próbkowania. Ta wartość 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 wraz z nazwami danych. Kolejność wymiarów i danych jest taka sama jak określona w żądaniu za pomocą parametrów metrics i dimensions. Liczba nagłówków to liczba wymiarów + liczba danych.
columnHeaders[].name string Nazwa wymiaru lub rodzaju danych.
columnHeaders[].columnType string Typ kolumny. "wymiar" &"METRIC&&tt.
columnHeaders[].dataType string Typ danych. Typ nagłówka danych w kolumnie wymiaru to STRING. Nagłówki kolumn danych zawierają typy danych dla takich wartości jak INTEGER, PERCENT, TIME, CURRENCY, FLOAT itd. Wszystkie możliwe typy danych znajdziesz w odpowiedzi interfejsu API metadanych.
totalsForAllResults object Łączna wartość dla żądanych wskaźników w postaci par klucz-wartość nazw i wartości. Kolejność tabel wskaźników jest taka sama jak kolejność wskaźników w żądaniu.
dataTable object Obiekt tabeli danych, którego można używać z Wykresami Google.
dataTable.cols[] list Lista deskryptorów kolumn z wymiarami i innymi danymi. Kolejność wymiarów i danych jest taka sama jak określona w żądaniu za pomocą parametrów metrics i dimensions. Liczba kolumn to liczba wymiarów + liczba danych.
dataTable.cols[].id string Identyfikator, który służy do odwoływania się do określonej kolumny (a nie do użycia indeksu kolumn). Identyfikator wymiaru lub wskaźnika jest używany do ustawienia tej wartości.
dataTable.cols[].label string Etykieta kolumny (która może być wyświetlana w formie wizualizacji). Identyfikator wymiaru lub danych służy do określenia tej wartości.
dataTable.cols[].type string Typ danych w tej kolumnie.
dataTable.rows[] list Wiersze danych Analytics w formacie tabeli danych, w którym każdy wiersz to obiekt zawierający listę wartości komórek dla wymiarów, a następnie wskaźniki. Kolejność wymiarów i danych jest taka sama jak określona w żądaniu. W każdej komórce znajduje się lista N pól, gdzie N = liczba wymiarów + liczba danych.

Kody błędów

Jeśli żądanie się powiedzie, podstawowy interfejs API do 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 korzysta z interfejsu Analytics API, musi zaimplementować prawidłową obsługę błędów. Szczegółowe informacje na temat kodów błędów i sposobu ich obsługi znajdziesz w przewodniku po odpowiedziach na błędy.

Spróbuj!

Możesz wypróbować zapytania kierowane do interfejsu Core Reporting API.

  • Aby zobaczyć 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 tabeli z wartościami dla wszystkich określonych danych i wymiarów.

  • Aby wysłać żądanie dotyczące aktywnych danych i wyświetlić odpowiedź w formacie JSON, spróbuj użyć metody analytics.data.ga.get w eksploratorze interfejsów API danych Google.

Próbkowanie

Google Analytics oblicza na bieżąco określone kombinacje wymiarów i danych. Aby zwrócić dane w rozsądnym terminie, Google Analytics może przetworzyć tylko ich próbkę.

Możesz określić poziom próbkowania dla żądania, ustawiając parametr samplingLevel.

Jeśli odpowiedź interfejsu Core Reporting API zawiera próbkowane dane, pole containsSampledData będzie mieć wartość true. Dodatkowo 2 usługi będą zawierać informacje o poziomie próbkowania zapytania: sampleSize i sampleSpace. Dzięki tym 2 wartościom możesz obliczyć procent sesji, które zostały użyte dla zapytania. Jeśli np.sampleSize ma wartość 201,000, a sampleSpace to 220,000,raport powstaje na podstawie (201 000 / 220 000) * 100 = 91,36% sesji.

Ogólny opis próbkowania i sposób jego użycia w Google Analytics znajdziesz w artykule o próbkowaniu.


Obsługa dużych ilości danych

Jeśli spodziewasz się, że zapytanie zwróci duży zestaw wyników, skorzystaj z wskazówek poniżej, aby zoptymalizować zapytanie do interfejsu API, uniknąć błędów i zminimalizować limity. Pamiętaj, że ustawiamy wartość bazową skuteczności, określając maksymalnie 7 wymiarów i 10 danych w jednym żądaniu interfejsu API. Przetworzenie niektórych zapytań określających dużą liczbę danych i wymiarów może zająć więcej czasu niż inne, ale ograniczenie liczby żądanych wskaźników może nie wystarczyć, aby zwiększyć wydajność zapytań. Aby uzyskać najlepszą wydajność, możesz użyć następujących metod.

Zmniejszanie wymiarów na zapytanie

W jednym żądaniu API można określić maksymalnie 7 wymiarów. Często Google Analytics musi na bieżąco obliczać wyniki tych złożonych zapytań. Może to być szczególnie czasochłonne, jeśli liczba powstałych wierszy jest duża. Na przykład zapytania według słów kluczowych według miasta mogą odpowiadać milionom wierszy danych. Aby poprawić skuteczność, zmniejsz liczbę wierszy przetwarzanych przez Google Analytics, ograniczając liczbę wymiarów w zapytaniu.

Dzielenie zapytania na zakres dat

W takich przypadkach zalecamy utworzenie osobnych zapytań dla jednego tygodnia, a nawet jednego dnia naraz. W przypadku dużego zbioru danych nawet dane z jednego dnia mogą zwracać więcej niż max-results. W takim przypadku nie można uniknąć stronicowania. Jeśli jednak liczba wierszy pasujących do zapytania jest większa niż max-results, rozdzielenie zakresu dat może zmniejszyć łączny czas pobierania wyników. To podejście może poprawić wydajność zarówno w przypadku zapytań z jednym wątkiem, jak i zapytań równoległych.

Tempo

Podział wyników na strony może być dobrym sposobem na podzielenie dużych zbiorów na segmenty, którymi można zarządzać. Pole totalResults informuje o tym, ile jest pasujących wierszy, a itemsPerPage udostępnia maksymalną liczbę wierszy, które mogą zostać zwrócone w wyniku. Jeśli współczynnik proporcji totalResults do itemsPerPage jest wysoki, poszczególne zapytania mogą trwać dłużej niż jest to konieczne. Jeśli potrzebujesz tylko ograniczonej liczby wierszy, na przykład do wyświetlania, może Ci się przydać możliwość wyraźnego określenia rozmiaru odpowiedzi w parametrze max-results. Jeśli jednak Twoja aplikacja musi przetworzyć cały zbiór wyników, żądanie większej liczby dozwolonych wierszy może być skuteczniejsze.

Za pomocą programu gzip

Prosty i wygodny sposób na zmniejszenie przepustowości wymaganej dla każdego żądania to włączenie kompresji gzip. Chociaż zdekompresowanie wyników wymaga dodatkowego czasu na procesory, kompromis między kosztami sieci jest zwykle bardzo wartościowy. 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 poprawnych nagłówków HTTP, które pomogą Ci włączyć kompresję gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)