Przewodnik po migracji

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 lub DESCENDING) w polu sortOrder.

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 raportu

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.\" }"
   }
  ]
 }
}