遷移指南

本指南提供指南，協助您將 Core Reporting API v3 遷移至 Analytics Reporting API v4。

簡介

如要運用 Analytics (分析) Reporting API v4 新推出的功能，請遷移程式碼以使用 API。本指南顯示的是 Core Reporting API v3 中的要求，以及 Analytics Reporting API v4 中的同等要求，幫助您簡化遷移作業。

Python 遷移

如果您是 Python 開發人員，請使用 GitHub 上的 GAV4 輔助程式庫，將 Google Analytics Core Reporting API v3 要求轉換為 Analytics Reporting API v4 要求。

端點

Core Reporting API v3 和 Analytics 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、JavaScript 或其他需使用 Google Discovery 服務的用戶端程式庫，則必須提供探索文件的位置給 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')

JavaScript

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

Java 和 PHP 用戶端程式庫已預先建構，但您可以使用探索服務和 Google API 產生器來產生這類程式庫。

要求

API v4 參考資料詳細說明要求主體的結構。以下各節說明如何將 v3 要求參數遷移至 v4 要求參數。

資料檢視 ID

在第 3 版中，接受「資料表 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",
    ...
  }]
}

日期範圍

Analytics Reporting API v4 可讓您在單一要求中指定多個日期範圍。dateRanges 欄位會使用 DateRange 物件清單。在第 3 版中，您需要使用 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"
    }],
    ....
  }]
}

指標

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

尺寸

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

排序

第 3 版 sort 參數相當於使用 OrderBy 物件清單的 v4 orderBys 欄位。

在第 4 版中，依照維度或指標值排序結果：

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

取樣層級

第 3 版 samplingLevel 參數對應至第 4 版 samplingLevel 欄位。在 v3 中，可接受的 samplingLevel 值為 FASTER、HIGHER_PRECISION 和 DEFAULT；在 v4 中，可接受的 samplingLevel 值為 SMALL、LARGE 和 DEFAULT。請注意，第 3 版中的 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"
  }]
}

路段

第 3 版 segment 參數會對應至使用 Segment 物件清單的 v4 segments 欄位。

區隔 ID

在第 4 版中，如要透過區隔 ID 要求區隔，請建構 Segment 物件，並透過 segmentId 欄位提供其 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"]
                    }
                  }]
                }]
              }]
            }
          }]
        }
      }
    }]
  }]

第 4 版中的 v3 區隔語法

v4 API 中的 segmentId 欄位支援 v3 API 中的區隔語法。

以下範例說明 v4 中同等要求的 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"
    }]
  }]
}

濾鏡

第 4 版會使用 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"]
            }]
      }]
  }]

第 4 版中的 v3 篩選器語法

雖然第 4 版的 filtersExpression 欄位支援第 3 版中的 filters 語法，但請使用 dimensionFilterClauses 和 metricFilterClauses 來篩選維度和指標。

以下範例說明 v4 中同等要求的 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"
  }]
}

空白列

第 3 版 include-empty-rows 參數對應到第 4 版中的 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",
  }]
}

分頁

第 4 版會使用 pageToken 和 pageSize 欄位，將大量結果分頁。系統會從回應物件的 nextPageToken 屬性取得 pageToken。

以下範例將 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",
  }]
}

標準參數

Analytics 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，您會在回應中收到對應的報告。

報表

v4 報表有三個頂層欄位：columnHeader、data 和 nextPageToken。

就 v3 回應而言，v4 回應主體不包含所有查詢參數的回應，因此如要取得特定查詢參數的回應，用戶端應用程式必須將該參數新增至 ReportRequest。

我們已處理「Pagination」區段中的 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 會在資料列陣列中傳回報表資料，其中包含要求的維度和指標。

Analytics 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 會傳回布林值欄位 containsSampledData (設為 true)。

如果資料經過取樣，Analytics 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

下方的回應範例含有來自兩個日期範圍的要求取樣資料。結果是依據約 1,500 萬個工作階段的取樣空間大小從近 50 萬個樣本計算得出：

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

剖析 v4 回應

下列程式碼範例會剖析並列印 Analytics 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

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

處理錯誤

由於第 4 版中的 error response 格式與第 3 版不同，因此請更新程式碼，以便處理 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.\" }"
   }
  ]
 }
}