W tym przewodniku znajdziesz wskazówki, jak przenieść interfejs Core Reporting API v3 do interfejsu Analytics Reporting API w wersji 4.
Wstęp
Aby korzystać z nowych funkcji wprowadzonych w interfejsie Analytics Reporting API w wersji 4, przenieś swój kod do tego interfejsu. Aby ułatwić Ci migrację, w tym przewodniku przedstawiamy żądania w interfejsie API podstawowego raportowania w wersji 3 i odpowiadające im żądania w interfejsie Analytics Reporting API w wersji 4.
Migracja Pythona
Jeśli jesteś programistą w Pythonie, użyj biblioteki pomocniczej GAV4 na GitHubie, aby przekonwertować żądania Google Analytics Core Reporting API v3 na żądania do interfejsu Analytics Reporting API v4
Punkty końcowe
Interfejs API podstawowego raportowania w wersji 3 i Analytics Reporting API w wersji 4 mają różne punkty końcowe i metody HTTP:
Punkt końcowy w wersji 3
GET https://www.googleapis.com/analytics/v3/data/ga
Punkt końcowy w wersji 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
W poniższych przykładach porównano żądanie w wersji 3 i odpowiadającego mu żądania w wersji 4:
v3
Dokumentacja źródłowa wersji 3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users&dimensions=ga:pagePath
v4
Dokumentacja źródłowa wersji 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
}],
"dimensions": [
{
"name":"ga:pagePath"
}]
}]
}
Biblioteki klienta i usługa wykrywania
Jeśli używasz biblioteki Python, JavaScript lub innej biblioteki klienta, która korzysta z Google Discovery Service, musisz podać lokalizację dokumentu wykrywania na potrzeby interfejsu Reporting API w wersji 4.
Python
from apiclient import discovery
...
# Build the Analytics Reporting API v4 authorized service object.
analyticsReporting = discovery.build(
'analyticsreporting',
'v4',
http=http,
discoveryServiceUrl='https://analyticsreporting.googleapis.com/$discovery/rest')
JavaScript
gapi.client.load(
'https://analyticsreporting.googleapis.com/$discovery/rest',
'v4'
).then(...)
Biblioteki klienta Java i PHP są gotowe, ale możesz je wygenerować za pomocą usługi wykrywania i generatora interfejsów API Google.
Prośby
Dokumentacja interfejsu API w wersji 4 szczegółowo opisuje strukturę treści żądania. W sekcjach poniżej opisujemy migrację parametrów żądania w wersji 3 do parametrów żądania w wersji 4.
Wyświetl identyfikatory
W wersji 3 parametr ids
, który akceptuje „identyfikator tabeli”, ma format ga:XXXX
, gdzie XXXX
to identyfikator widoku (profilu). W wersji 4 identyfikator widoku (profilu) jest określony w polu viewId
w treści żądania.
W tych przykładach porównano parametr ids
w żądaniu w wersji 3 i pole viewId
w żądaniu w wersji 4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
...
}]
}
Zakresy dat
Interfejs Analytics Reporting API w wersji 4 umożliwia określenie wielu zakresów dat w jednym żądaniu. Pole dateRanges
zawiera listę obiektów DateRange.
W wersji 3 możesz używać parametrów start-date
i end-date
do określania zakresu dat w żądaniu.
W poniższych przykładach porównano parametry start-date
i end-date
w żądaniu w wersji 3 oraz pole dateRanges
w żądaniu w wersji 4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
....
}]
}
Wskaźniki
Parametr metrics
w wersji 3 odpowiada polu metrics
w wersji 4, które pobiera listę obiektów Wskaźnik.
Poniższe przykłady porównują parametry metrics
w żądaniu w wersji 3 i pola metrics
w żądaniu w wersji 4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users,ga:sessions \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
},{
"expression":"ga:sessions"
}],
...
}]
}
Wymiary
Parametr dimensions
w wersji 3 odpowiada polu dimensions
w wersji 4, które zawiera listę obiektów Wymiar.
Poniższe przykłady porównują parametry dimensions
w żądaniu w wersji 3 i pola dimensions
w żądaniu w wersji 4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&dimensions=ga:country,ga:browser&... \
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"dimensions": [
{
"name":"ga:country"
},{
"name":"ga:browser"
}],
...
}]
}
Sortowanie
Parametr sort
w wersji 3 jest odpowiednikiem pola orderBys
w wersji 4, które pobiera listę obiektów OrderBy.
Aby posortować wyniki według wymiaru lub wartości danych, w wersji 4:
- Podaj jego nazwę lub alias w polu
fieldName
. - Określ kolejność sortowania (
ASCENDING
lubDESCENDING
) w polusortOrder
.
W poniższych przykładach porównano parametr sort
w żądaniu w wersji 3 i pole orderBy
w żądaniu wersji 4. Oba te sposoby sortują użytkowników w kolejności malejącej, a źródła alfabetycznie:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&sort=-ga:users,ga:source
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"orderBys": [
{
"fieldName": "ga:users",
"sortOrder": "DESCENDING"
},{
"fieldName": "ga:source"
}],
}]
}
Poziom próbkowania
Parametr samplingLevel
w wersji 3 odpowiada polu samplingLevel
w wersji 4. W wersji 3 akceptowane wartości samplingLevel
to FASTER
, HIGHER_PRECISION
i DEFAULT
, a w wersji 4 akceptowane wartości samplingLevel
to SMALL
, LARGE
i DEFAULT
.
Pamiętaj, że FASTER
w wersji 3 zmieniono na SMALL
w wersji 4 i z HIGHER_PRECISION
na LARGE
.
Poniższe przykłady porównują parametr samplingLevel
w żądaniu w wersji 3 i pole samplingLevel
w żądaniu w wersji 4:
v3
https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX ...\
samplingLevel=HIGHER_PRECISION
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"samplingLevel": "LARGE"
}]
}
Segmenty
Parametr segment
w wersji 3 odpowiada polu wersji 4 segments
, które zawiera listę obiektów Segment.
Identyfikatory segmentów
Aby zażądać segmentu według identyfikatora segmentu, utwórz w wersji 4 obiekt Segment i podaj jego identyfikator w polu segmentId.
Poniższe przykłady porównują parametr segment
w żądaniu w wersji 3 i pole segments
w żądaniu w wersji 4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=gaid::-11
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "gaid::-11"
}]
}]
}
Segmenty dynamiczne
Aby wyrazić bardziej skomplikowane definicje segmentów w wersji 4, użyj pola segments
, które zawiera obiekt DynamicSegment.
Poniższe przykłady porównują parametr segment
w żądaniu w wersji 3 i pole segments
zawierające obiekt DynamicSegment
w żądaniu w wersji 4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"sessionSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:medium",
"operator": "EXACT",
"expressions": [ "referral" ]
}
}]
}]
}
}]
}
}
}]
}]
}
W segmencie możesz łączyć warunki i sekwencje:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=users::condition::ga:revenue>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:medium"}, {"name":"ga:segment"}],
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"userSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"metricFilter": {
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "10"
}
}]
}]
}
},
{
"sequenceSegment": {
"segmentSequenceSteps": [{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["desktop"]
}
}]
}],
"matchType": "PRECEDES"
},{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["mobile"]
}
}]
}]
}]
}
}]
}
}
}]
}]
Składnia segmentów w wersji 3 w wersji 4
Pole segmentId w interfejsie API w wersji 4 obsługuje składnię segmentów w interfejsie API wersji 3.
W tych przykładach widać, jak pole segmentId
w odpowiednim żądaniu w wersji 4 obsługuje parametr segment
w żądaniu w wersji 3:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "sessions::condition::ga:medium==referral"
}]
}]
}
Filtry
Wersja 4 używa dimensionFilterClauses
do filtrowania wymiarów i metricFilterClauses
do filtrowania danych. Element dimensionFilterClauses
zawiera listę obiektów DimensionFilter, a metricFilterClauses
– listę obiektów MetricFilter.
Poniższe przykłady porównują parametr filters
w żądaniu w wersji 3 i pole dimensionFilterClauses
w żądaniu w wersji 4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-06-01&end-date=2015-07-31&metrics=ga:users& \
dimensions=ga:browser&filters=ga:browser==Firefox
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:browser"}, {"name":"ga:country"}],
"dimensionFilterClauses": [{
"filters": [{
"dimension_name": "ga:browser",
"operator": "EXACT",
"expressions": ["Firefox"]
}]
}]
}]
Składnia filtrów w wersji 3 w wersji 4
Chociaż pole filtersExpression w wersji 4 obsługuje składnię filters
w wersji 3, do filtrowania wymiarów i danych możesz używać dimensionFilterClauses
i metricFilterClauses
.
W tych przykładach widać, jak pole filtersExpression
w odpowiednim żądaniu w wersji 4 obsługuje parametr filters
w żądaniu w wersji 3:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga%XXXX \
&filters=ga:browser==Firefox
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"filtersExpression": "ga:browser==Firefox"
}]
}
Puste wiersze
Parametr include-empty-rows
w wersji 3 odpowiada polu includeEmptyRows
w wersji 4. W wersji 3 domyślna wartość to true, a w wersji 4 wartość domyślna to false. Jeśli nie masz wartości ustawionej w wersji 3, musisz w niej ustawić prawda.
Poniższe przykłady porównują parametr include-empty-rows
w żądaniu w wersji 3 z polem includeEmptyRows
w żądaniu w wersji 4:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&include-empty-rows=true
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"includeEmptyRows": "true",
}]
}
Podział na strony
Wersja 4 wykorzystuje pola pageToken
i pageSize
do dzielenia na strony dużej liczby wyników. Wartość pageToken
jest pobierana z właściwości nextPageToken
obiektu odpowiedzi.
Poniższe przykłady porównują parametry start-index
i max-results
w żądaniu w wersji 3 z polami pageToken
i pageSize
w żądaniu w wersji 4:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&start-index=10001&max-results=10000
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
Parametry standardowe
Interfejs Analytics Reporting API w wersji 4 obsługuje większość standardowych parametrów zapytań stosowanych w interfejsie API wersji 3, z wyjątkiem parametrów userIp
i callback
.
Poniższe przykłady porównują parametr quotaUser
w żądaniu w wersji 3 z parametrem w żądaniu wersji 4:
Punkt końcowy w wersji 3
GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2
Punkt końcowy w wersji 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2
Odpowiedzi
Wersja 4 umożliwia przesłanie wielu obiektów ReportRequest w jednym żądaniu HTTP, dlatego w odpowiedzi otrzymujesz tablicę obiektów raportów. W przypadku każdego przesłanego żądania ReportRequest otrzymasz w odpowiedzi odpowiedni Raport.
Raporty
Raport w wersji 4 zawiera 3 pola najwyższego poziomu: columnHeader
, data
i nextPageToken
.
Ponieważ treść odpowiedzi w wersji 4 nie zawiera odpowiedzi na wszystkie parametry zapytania, tak jak ma to w przypadku odpowiedzi v3, aby uzyskać odpowiedź na określony parametr zapytania, aplikacja kliencka musi dodać ten parametr do żądania ReportRequest.
nextPageToken
omówiliśmy już w sekcji Pagination, więc przyjrzyjmy się najpierw obiektowi columnHeader.
Nagłówek kolumny
Nagłówek kolumny zawiera listę nazwanych wymiarów i obiekt MetricHeader, który zawiera listę obiektów MetricHeaderEntry. Każdy obiekt MetricHeaderEntry określa dane name
i ich type
(waluta, wartość procentowa itp.).
, co ułatwia formatowanie danych wyjściowych.
W poniższych przykładach porównano pole columnHeaders
w odpowiedzi w wersji 3 z polem columnHeader
w odpowiedzi w wersji 4:
v3
"columnHeaders": [
{
"name":"ga:source",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:city",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:sessions",
"columnType":"METRIC",
"dataType":"INTEGER"
},{
"name":"ga:pageviews",
"columnType":
"METRIC",
"dataType":"INTEGER"
}
]
v4
"columnHeader": {
"dimensions": [
"ga:source",
"ga:city"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:pageviews",
"type": "INTEGER"
},
{
"name": "ga:sessions",
"type": "INTEGER"
}
]
}
},
Wiersze raportu
Interfejs API podstawowego raportowania w wersji 3 zwraca dane raportu w tablicy rows, która zawiera żądane wymiary i dane.
Interfejs Analytics Reporting API w wersji 4 zwraca dane raportu w obiekcie ReportRow, który zawiera tablicę wymiarów i tablicę obiektów DateRangeValues. Każdy z nich zawiera jeden lub dwa zakresy dat, tak jak na tym diagramie:
Wiersze
v3
"rows": [
[
"google",
"Philadelphia",
"60",
"5"
],
[
"google",
"Johnstown",
"21",
"1"
],
[
"google",
"Progress",
"7",
"1"
]
],
v4
"rows": [
{
"dimensions": [
"google",
"Philadelphia"
],
"metrics": [
{
"values": [
"60",
"5"
]
}
]
},
{
"dimensions": [
"google",
"Johnstown"
],
"metrics": [
{
"values": [
"21",
"1"
]
}
]
},
{
"dimensions": [
"google",
"Progress"
],
"metrics": [
{
"values": [
"7",
"1"
]
}
]
}
],
Próbkowane dane
Jeśli wyniki są spróbkowane, interfejs API podstawowego raportowania w wersji 3 zwraca pole wartości logicznej containsSampledData
z wartością true
.
Jeśli dane są próbkowane, interfejs Analytics Reporting API w wersji 4 nie zwraca wartości logicznej. Zamiast tego zwraca pola samplesReadCounts
i samplingSpaceSizes
.
Jeśli wyniki nie są spróbkowane, pola nie zostaną zdefiniowane.
Poniższy przykład w Pythonie pokazuje, jak sprawdzić, czy raport zawiera próbkowane dane:
def ContainsSampledData(report):
"""Determines if the report contains sampled data.
Args:
report (Report): An Analytics Reporting API v4 response report.
Returns:
bool: True if the report contains sampled data.
"""
report_data = report.get('data', {})
sample_sizes = report_data.get('samplesReadCounts', [])
sample_spaces = report_data.get('samplingSpaceSizes', [])
if sample_sizes and sample_spaces:
return True
else:
return False
Poniżej znajdziesz przykładową odpowiedź, która zawiera próbkowane dane z żądania z 2 zakresami dat. Wyniki zostały obliczone na podstawie prawie 500 tys. próbek z przestrzeni próbek o rozmiarze około 15 milionów sesji:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
Analizowanie odpowiedzi V4
Ten przykładowy kod analizuje i wyświetla odpowiedź interfejsu Analytics Reporting API w wersji 4:
Python
def printResponse(self, response):
"""Parses and prints the Analytics Reporting API v4 response"""
for report in response.get('reports', []):
columnHeader = report.get('columnHeader', {})
dimensionHeaders = columnHeader.get('dimensions', [])
metricHeaders = columnHeader.get('metricHeader', {}).get('metricHeaderEntries', [])
rows = report.get('data', {}).get('rows', [])
for row in rows:
dimensions = row.get('dimensions', [])
dateRangeValues = row.get('metrics', [])
for header, dimension in zip(dimensionHeaders, dimensions):
print header + ': ' + dimension
for i, values in enumerate(dateRangeValues):
print 'Date range (' + str(i) + ')'
for metricHeader, value in zip(metricHeaders, values.get('values')):
print metricHeader.get('name') + ': ' + value
Java
public static void printResponse(GetReportsResponse response) {
for (Report report: response.getReports()) {
ColumnHeader header = report.getColumnHeader();
List<String> dimensionHeaders = header.getDimensions();
List<MetricHeaderEntry> metricHeaders = header.getMetricHeader().getMetricHeaderEntries();
List<ReportRow> rows = report.getData().getRows();
for (ReportRow row: rows) {
List<String> dimensions = row.getDimensions();
List<DateRangeValues> metrics = row.getMetrics();
for (int i = 0; i < dimensionHeaders.size() && i < dimensions.size(); i++) {
System.out.println(dimensionHeaders.get(i) + ": " + dimensions.get(i));
}
for (int j = 0; j < metrics.size(); j++) {
System.out.print("Date Range (" + j + "): ");
DateRangeValues values = metrics.get(j);
for (int k = 0; k < values.size() && k < metricHeaders.size(); k++) {
System.out.println(metricHeaders.get(k).getName() + ": " + values.get(k));
}
}
}
}
}
Obsługa błędów
Ponieważ format odpowiedzi na błąd w wersji 4 jest inny niż w wersji 3, zaktualizuj swój kod tak, by obsługiwał odpowiedzi na błędy wersji 4.
Poniżej znajdziesz porównanie odpowiedzi o błędzie w wersji 3 i odpowiadającej mu odpowiedzi w wersji 4:
v3
{
"error": {
"errors": [
{
"domain": "global",
"reason": "insufficientPermissions",
"message": "User does not have sufficient permissions for this profile.",
}
],
"code": 403,
"message": "User does not have sufficient permissions for this profile."
}
}
v4
{
"error": {
"code": 403,
"message": "User does not have sufficient permissions for this profile.",
"status": "PERMISSION_DENIED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "[ORIGINAL ERROR] generic::permission_denied: User does not have sufficient permissions for this profile. [google.rpc.error_details_ext] { message: \"User does not have sufficient permissions for this profile.\" }"
}
]
}
}