이 페이지는 Cloud Translation API를 통해 번역되었습니다.

마이그레이션 가이드

이 가이드에서는 Core Reporting API v3을 애널리틱스 Reporting API v4로 이전하기 위한 가이드라인을 제공합니다.

소개

애널리틱스 Reporting API v4에 도입된 새로운 기능을 활용하려면 API를 사용하도록 코드를 이전하세요. 이 가이드에서는 더 쉽게 이전할 수 있도록 Core Reporting API v3의 요청과 이에 상응하는 애널리틱스 Reporting API v4 요청을 보여줍니다.

Python 마이그레이션

Python 개발자인 경우 GitHub의 GAV4 도우미 라이브러리를 사용하여 Google Analytics Core Reporting API v3 요청을 Analytics Reporting API v4 요청으로 변환합니다.

엔드포인트

Core Reporting API v3과 애널리틱스 Reporting API v4에는 엔드포인트와 HTTP 메서드가 다음과 같이 다릅니다.

v3 엔드포인트

GET https://www.googleapis.com/analytics/v3/data/ga

v4 엔드포인트

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet

다음 예는 v3의 요청과 v4의 해당 요청을 비교합니다.

v3

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&dimensions=ga:pagePath

v4

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"
    }],
    "dimensions": [
    {
      "name":"ga:pagePath"
    }]
  }]
}

클라이언트 라이브러리 및 검색 서비스

Python, 자바스크립트 또는 Google 검색 서비스를 사용하는 기타 클라이언트 라이브러리를 사용하는 경우 Reporting API v4의 검색 문서 위치를 제공해야 합니다.

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')

자바스크립트

gapi.client.load(
  'https://analyticsreporting.googleapis.com/$discovery/rest',
  'v4'
).then(...)

자바 및 PHP 클라이언트 라이브러리는 사전 빌드되어 있지만 검색 서비스와 Google API 생성기를 사용하여 생성할 수 있습니다.

요청

API v4 참조는 요청 본문의 구조를 자세히 설명합니다. 다음 섹션에서는 v3 요청 매개변수를 v4 요청 매개변수로 마이그레이션하는 방법을 설명합니다.

ID 보기

v3에서 '테이블 ID'를 허용하는 ids 매개변수는 ga:XXXX 형식이며, 여기서 XXXX는 뷰 (프로필) ID입니다. v4에서 뷰 (프로필) ID는 요청 본문의 viewId 필드에 지정됩니다.

다음 예는 v3 요청의 ids 매개변수와 v4 요청의 viewId 필드를 비교합니다.

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

기간

애널리틱스 Reporting API v4를 사용하면 단일 요청에 여러 기간을 지정할 수 있습니다. dateRanges 필드는 DateRange 객체 목록을 가져옵니다. v3에서는 start-date 및 end-date 매개변수를 사용하여 요청에 기간을 지정합니다.

다음 예는 v3 요청의 start-date 및 end-date 매개변수와 v4 요청의 dateRanges 필드를 비교합니다.

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

측정항목

v3 metrics 매개변수는 측정항목 객체 목록을 가져오는 v4 metrics 필드에 해당합니다.

다음 예는 v3 요청의 metrics 매개변수와 v4 요청의 metrics 필드를 비교합니다.

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

크기

v3 dimensions 매개변수는 측정기준 객체 목록을 가져오는 v4 dimensions 필드에 해당합니다.

다음 예는 v3 요청의 dimensions 매개변수와 v4 요청의 dimensions 필드를 비교합니다.

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

정렬

v3 sort 매개변수는 OrderBy 객체 목록을 사용하는 v4 orderBys 필드와 동일합니다.

v4에서 측정기준 또는 측정항목 값을 기준으로 결과를 정렬하는 방법은 다음과 같습니다.

fieldName 필드를 통해 이름 또는 별칭을 제공합니다.
sortOrder 필드를 통해 정렬 순서 (ASCENDING 또는 DESCENDING)를 지정합니다.

다음 예는 v3 요청의 sort 매개변수와 v4 요청의 orderBy 필드를 비교합니다. 둘 다 사용자를 내림차순으로 정렬하고 소스를 알파벳순으로 정렬합니다.

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"
    }],
  }]
}

샘플링 수준

v3 samplingLevel 매개변수는 v4 samplingLevel 필드에 해당합니다. v3에서 허용되는 samplingLevel 값은 FASTER, HIGHER_PRECISION, DEFAULT이고 v4에서 허용되는 samplingLevel 값은 SMALL, LARGE, DEFAULT입니다. v3의 FASTER이 v4의 SMALL, HIGHER_PRECISION의 LARGE로 변경되었습니다.

다음 예는 v3 요청의 samplingLevel 매개변수와 v4 요청의 samplingLevel 필드를 비교합니다.

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

세그먼트

v3 segment 매개변수는 세그먼트 객체 목록을 가져오는 v4 segments 필드에 해당합니다.

세그먼트 ID

v4에서 세그먼트 ID별로 세그먼트를 요청하려면 세그먼트 객체를 구성하고 세그먼트 ID 필드를 통해 ID를 제공합니다.

다음 예시에서는 v3 요청의 segment 매개변수와 v4 요청의 segments 필드를 비교합니다.

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

동적 세그먼트

v4에서 더 복잡한 세그먼트 정의를 표현하려면 DynamicSegment 객체를 포함하는 segments 필드를 사용합니다.

다음 예시에서는 v3 요청의 segment 매개변수와 v4 요청의 DynamicSegment 객체가 포함된 segments 필드를 비교합니다.

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

세그먼트에서 조건과 시퀀스를 결합할 수 있습니다.

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

v3의 v3 세그먼트 구문

v4 API의 SegmentId 필드는 v3 API의 세그먼트 구문을 지원합니다.

다음 예는 v3의 동등한 요청에 있는 segmentId 필드에서 v3 요청의 segment 매개변수가 어떻게 지원되는지 보여줍니다.

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

필터

v4는 dimensionFilterClauses를 사용하여 측정기준을 필터링하고 metricFilterClauses를 사용하여 측정항목을 필터링합니다. dimensionFilterClauses에는 DimensionFilter 객체 목록이 포함되고 metricFilterClauses에는 MetricFilter 객체 목록이 포함됩니다.

다음 예시에서는 v3 요청의 filters 매개변수와 v4 요청의 dimensionFilterClauses 필드를 비교합니다.

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

v3의 v3 필터 구문

v4의 filtersExpression 필드는 v3의 filters 구문을 지원하지만 dimensionFilterClauses 및 metricFilterClauses를 사용하여 측정기준과 측정항목을 필터링합니다.

다음 예는 v3의 동등한 요청에 있는 filtersExpression 필드에서 v3 요청의 filters 매개변수가 어떻게 지원되는지 보여줍니다.

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

빈 행

v3 include-empty-rows 매개변수는 v4의 includeEmptyRows 필드에 해당합니다. v3 매개변수는 기본적으로 true이고 v4의 기본값은 false입니다. v3에 값이 설정되어 있지 않으면 v4에서 값을 true로 설정해야 합니다.

다음 예시에서는 v3 요청의 include-empty-rows 매개변수를 v4 요청의 includeEmptyRows 필드와 비교합니다.

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",
  }]
}

페이지로 나누기

v4는 pageToken 및 pageSize 필드를 사용하여 많은 결과를 페이지로 나눕니다. pageToken는 응답 객체의 nextPageToken 속성에서 가져옵니다.

다음 예시는 v3 요청의 start-index 및 max-results 매개변수를 v4 요청의 pageToken 및 pageSize 필드와 비교합니다.

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",
  }]
}

표준 매개변수

애널리틱스 Reporting API v4는 v3 API에서 userIp 및 callback 매개변수를 제외한 대부분의 표준 쿼리 매개변수를 지원합니다.

다음 예는 v3 요청의 quotaUser 매개변수와 v4 요청의 매개변수를 비교합니다.

v3 엔드포인트

GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2

v4 엔드포인트

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2

응답

v4를 사용하면 단일 HTTP 요청으로 여러 ReportRequest 객체를 제출할 수 있으므로 응답에서 보고서 객체의 배열을 가져올 수 있습니다. 제출된 ReportRequest마다 응답에 해당하는 Report가 표시됩니다.

보고서

v4 보고서에는 columnHeader, data, nextPageToken의 세 가지 최상위 필드가 있습니다.

v4 응답 본문은 v3 응답과 달리 모든 쿼리 매개변수에 대한 응답을 포함하지 않으므로 특정 쿼리 매개변수에 대한 응답을 가져오려면 클라이언트 애플리케이션이 이 매개변수를 ReportRequest에 추가해야 합니다.

페이지 나누기 섹션에서 이미 nextPageToken을 다루었으므로 먼저 columnHeader 객체를 살펴보겠습니다.

열 헤더

열 헤더에는 명명된 측정기준 목록과 MetricHeader 객체 목록이 포함되어 있으며 이 객체는 MetricHeaderEntry 객체 목록을 포함합니다. 각 MetricHeaderEntry 객체는 측정항목 name 및 type (통화, 백분율 등)을 지정합니다. 이렇게 하면 출력 형식을 지정할 수 있습니다.

다음 예는 v3 응답의 columnHeaders 필드와 v4 응답의 columnHeader 필드를 비교합니다.

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"
            }
        ]
    }
},

보고서 행

Core Reporting API v3는 요청된 측정기준 및 측정항목이 포함된 rows 배열의 보고서 데이터를 반환합니다.

애널리틱스 Reporting API v4는 다음 다이어그램과 같이 ReportRow 객체에 보고서 데이터를 반환합니다. 이 객체는 측정기준의 배열과 DateRangeValues 객체의 배열을 포함합니다. 각 객체에는 하나 또는 두 개의 기간이 포함되어 있습니다.

보고서 행

행

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"
                ]
            }
        ]
    }
],

샘플링된 데이터

결과가 샘플링되면 Core Reporting API v3은 true로 설정된 부울 필드 containsSampledData를 반환합니다.

애널리틱스 Reporting API v4는 데이터가 샘플링된 경우 부울을 반환하지 않습니다. 대신 API가 samplesReadCounts 및 samplingSpaceSizes 필드를 반환합니다. 결과가 샘플링되지 않으면 이 필드가 정의되지 않습니다. 다음 Python 예에서는 보고서에 샘플링된 데이터가 포함되어 있는지 계산하는 방법을 보여줍니다.

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

다음은 기간이 2개인 요청의 샘플 데이터가 포함된 응답 예입니다. 결과는 약 1500만 개의 세션에 해당하는 샘플링 공간 크기의 50만 개 샘플에서 계산되었습니다.

{
  "reports":
  [
    {
      "columnHeader": {
        ...
      },
      "data": {
        ...
        "samplesReadCounts": [ "499630","499630"],
        "samplingSpaceSizes": ["15328013","15328013"],
      }
    }
  ]
}

v4 응답 파싱

다음 샘플 코드는 애널리틱스 Reporting API v4 응답을 파싱하고 출력합니다.

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

자바

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));
        }
      }
    }
  }
}

오류 처리

v4의 오류 응답 형식은 v3의 형식과 다르기 때문에 v4 오류 응답을 처리하도록 코드를 업데이트합니다.

다음 예시는 v3의 오류 응답과 v4의 동등한 오류 응답을 비교합니다.

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