Ten dokument zawiera pełne informacje na temat zapytań i odpowiedzi interfejsu API do raportowania ścieżek wielokanałowych.
Wstęp
Interfejs API do raportowania ścieżek wielokanałowych umożliwia pobieranie danych do raportu Ścieżki wielokanałowe Google Analytics. Każdy raport składa się ze statystyk uzyskanych z danych odesłanych do Analytics przez kod śledzenia, uporządkowanych jako wymiary i dane. Wybierając własne kombinacje wymiarów i danych, możesz używać interfejsu API do raportowania, aby tworzyć raporty niestandardowe dostosowane do Twoich potrzeb.
Interfejs API udostępnia jedną metodę, która żąda danych do raportu: report.get. Ta metoda podaje identyfikator tabeli odpowiadający widokowi (profilowi), z którego chcesz pobrać dane. Dodatkowo określasz te informacje:
- Kombinację wymiarów i danych.
- Zakres dat.
- Zbiór parametrów opcji, które określają, jakie dane są zwracane
Interfejs API udostępnia metodę report.get w punkcie końcowym REST: https://www.googleapis.com/analytics/v3/data/mcf. W tej sekcji znajdziesz przykładowe żądanie i opis każdego z parametrów.
Prośba
Interfejs API udostępnia jedną metodę wysyłania żądań danych:
analytics.data.mcf.get()
Do interfejsu API można też wysyłać zapytania jako punkt końcowy REST:
Authorization: Bearer {oauth2-token} GET https://www.googleapis.com/analytics/v3/data/mcf ?ids=ga:12345 &metrics=mcf:totalConversions,mcf:totalConversionValue &start-date=2011-10-01 &end-date=2011-10-31
Każdy parametr zapytania w adresie URL określa parametr zapytania w interfejsie API, który musi być zakodowany w adresie URL.
Wszystkie żądania wysyłane do interfejsu API do raportowania ścieżek wielokanałowych muszą być autoryzowane, najlepiej OAuth 2.0.
Podsumowanie parametrów zapytania
W tabeli poniżej znajdziesz podsumowanie wszystkich parametrów zapytania akceptowanych w interfejsie API do raportowania ścieżek wielokanałowych. 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. mcf:totalConversions,mcf:totalConversionValue.
Prawidłowe zapytanie musi określać co najmniej 1 wskaźnik. |
dimensions |
string |
nie | Lista rozdzielonych przecinkami wymiarów raportu Ścieżki wielokanałowe, np. mcf:source,mcf:keyword. |
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. |
samplingLevel |
string |
nie | Żądany poziom próbkowania. Dozwolone wartości:
|
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. |
Szczegóły parametru zapytania
ids
ids=ga:12345
ga: z identyfikatorem widoku (profilu) raportu. Możesz pobrać identyfikator widoku danych (profilu) na potrzeby raportu, korzystając z metody analytics.management.profiles.list, która udostępnia obiekt id w zasobie widoku (profilu) w
interfejsie Google Analytics Management API.
data rozpoczęcia
start-date=2011-10-01
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 2011-01-01.
start-date nie ma górnego limitu.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=2011-10-31
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=mcf:source,mcf:keyword
Parametr wymiarów określa klucze podstawowych danych na potrzeby
raportu Ścieżki wielokanałowe, np. mcf:source lub mcf:medium.
Używaj wymiarów do podziału danych o konwersjach na segmenty. Możesz np. zapytać o łączną liczbę konwersji dokonanych w Twojej witrynie, ale ciekawsze może być podanie liczby konwersji posegmentowanych według medium.
W takim przypadku zobaczysz liczbę konwersji z bezpłatnych wyników wyszukiwania, odesłań, e-maili itd.
Gdy używasz funkcji dimensions w żądaniu danych, 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. Musisz połączyć żądane wymiary z co najmniej 1 rodzajem danych.
Niedostępne wartości
Gdy nie można określić wartości wymiaru, Analytics używa specjalnego ciągu znaków (not set).
metrics
metrics=mcf:totalConversions,mcf:totalConversionValue
Zbiorcze statystyki aktywności użytkowników w Twojej witrynie, np. łączna liczba lub łączna wartość konwersji.
Jeśli zapytanie nie ma parametru dimensions, zwracane dane zawierają zbiorcze wartości dla żądanego zakresu dat, takie jak ogólna łączna wartość konwersji. Przy żądaniu wymiarów wartości są jednak posegmentowane według wartości wymiaru.
Na przykład żądanie mcf:totalConversions za pomocą funkcji mcf:source zwraca łączną liczbę konwersji na źródło.
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.
sortuj
sort=mcf:source,mcf:medium
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. Aby np. odpowiedzieć na pytanie „Jakie są moje najczęstsze źródła konwersji i za pomocą jakich mediów?”
możesz utworzyć zapytanie z tym parametrem. Kolumna sortuje ją najpierw według parametru mcf:source, a następnie według wartości mcf:medium, w kolejności rosnącej:
sort=mcf:source,mcf:medium
Aby uzyskać odpowiedź na pytanie „Jakie mam najskuteczniejsze media konwersji i z jakich źródeł?”, możesz utworzyć zapytanie z podanym niżej parametrem. Jest sortowana najpierw według kolumny mcf:medium, a następnie według kryterium mcf:source, zarówno w kolejności rosnącej:
sort=mcf:medium,mcf:source
Korzystając z parametru sort, pamiętaj o tych kwestiach:
- Sortuj tylko według wymiarów lub wartości danych użytych w parametrach
dimensionslubmetrics. 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=mcf: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 mcf:totalConversions i mcf:source dla widoku (profilu) 12134, gdzie wymiar mcf:medium to ciąg referral:
https://www.googleapis.com/analytics/v3/data/mcf ?ids=mcf:12134 &dimensions=mcf:source &metrics=mcf:totalConversions &filters=mcf:medium%3D%3Dreferral &start-date=2011-10-01 &end-date=2011-10-31
Więcej informacji znajdziesz w dokumentacji interfejsu API podstawowego raportowania.
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.max-results
max-results=100
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 API do raportowania ścieżek wielokanałowych zwraca maksymalnie 10 000 wierszy na żądanie niezależnie od tego, ile z nich poprosisz. Jeśli nie ma oczekiwanej liczby segmentów wymiarów, liczba wierszy może być mniejsza od żądanej. Na przykład możliwych wartości parametru mcf:medium jest mniej niż 300, więc przy segmentowaniu tylko według medium nie możesz uzyskać więcej niż 300 wierszy, nawet jeśli ustawisz wyższą wartość max-results.
Odpowiedź
Jeśli żądanie się powiedzie, zwróci treść odpowiedzi ze strukturą JSON zdefiniowaną 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.
Format odpowiedzi
{
"kind": "analytics#mcfData",
"id": string,
"query": {
"start-date": string,
"end-date": string,
"ids": string,
"dimensions": [
string
],
"metrics": [
string
],
"sort": [
string
],
"filters": string,
"samplingLevel": string,
"start-index": integer,
"max-results": integer
},
"itemsPerPage": integer,
"totalResults": integer,
"selfLink": string,
"previousLink": string,
"nextLink": string,
"profileInfo": {
"profileId": string,
"accountId": string,
"webPropertyId": string,
"internalWebPropertyId": string,
"profileName": string,
"tableId": string
},
"containsSampledData": boolean,
"sampleSize": string,
"sampleSpace": string,
"columnHeaders": [
{
"name": string,
"columnType": string,
"dataType": string
}
],
"totalsForAllResults": [
{
metricName: string,
...
}
]
"rows": [
[
McfData.Rows
]
],
}
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#mcfData”. |
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.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.samplingLevel |
string |
Requested sampling level. |
query.start-index |
integer |
Początkowy indeks wierszy. Wartość domyślna to 1. |
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.
|
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. Nagłówki kolumn wymiarów mają jako typ danych tylko "STRING" lub "MCF_SEQUENCE".
Nagłówki kolumn danych zawierają typy danych dla wartości danych, np. "INTEGER", "DOUBLE", "CURRENCY" itp. |
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 raportu, z których każdy zawiera listę Obiekt
{
"primitiveValue": "2183"
}
{
"conversionPathValue": [
{
"interactionType" : "CLICK",
"nodeValue" : "google"
},
{
"interactionType" : "CLICK",
"nodeValue" : "google"
}
]
}
|
Kody błędów
Jeśli żądanie zostanie zrealizowane, interfejs API do raportowania ścieżek wielokanałowych 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
Użyj eksploratora interfejsów API poniżej, aby wywołać tę metodę na aktywnych danych i zobaczyć odpowiedź.
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 do raportowania ścieżek wielokanałowych 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)