遷移指南

本指南說明如何將 Core Reporting API 第 3 版遷移至 Analytics (分析) Reporting API v4。

簡介

如要運用 Analytics (分析) Reporting API v4 中導入的功能,請將程式碼遷移至 API。本指南說明 Core Reporting API 第 3 版中的要求和 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

以下範例會比較第 3 版中的要求和 v4 中的對等要求:

v3

第 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

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 Service,則需要提供 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

在 v3 中,可接受「資料表 ID」的 ids 參數採用 ga:XXXX 格式,其中 XXXX 是檢視畫面 (設定檔) ID。在 v4 中,系統會在要求主體的 viewId 欄位中指定檢視表 (設定檔) ID。

以下範例比較 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 物件清單。在 v3 中,您可以使用 start-dateend-date 參數在要求中指定日期範圍。

以下範例比較 v3 要求中的 start-dateend-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 欄位指定排序順序 (ASCENDINGDESCENDING)。

以下範例會比較 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 值為 FASTERHIGHER_PRECISIONDEFAULT;在 v4 中,可接受的 samplingLevel 值為 SMALLLARGEDEFAULT。請注意,第 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"
  }]
}

路段

v3 segment 參數會對應至 v4 segments 欄位,該欄位會列出區隔物件清單。

區隔 ID

在 v4 中,如要依區隔 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"
    }]
  }]
}

動態區隔

在第 4 版中,如要呈現更複雜的區隔定義,請使用包含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"]
                    }
                  }]
                }]
              }]
            }
          }]
        }
      }
    }]
  }]

v4 中的 v3 區隔語法

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

以下範例說明第 4 版中對等要求中的 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"]
            }]
      }]
  }]

v4 中的 v3 篩選器語法

雖然 v4 的 filtersExpression 欄位支援 v3 中的 filters 語法,但請使用 dimensionFilterClausesmetricFilterClauses 篩選維度和指標。

以下範例說明第 4 版中對等要求中的 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 參數對應至 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",
  }]
}

分頁

第 4 版會使用 pageTokenpageSize 欄位,在大量結果中進行分頁。系統會從回應物件的 nextPageToken 屬性取得 pageToken

以下範例比較 v3 要求中的 start-indexmax-results 參數與 v4 要求中的 pageTokenpageSize 欄位:

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 中的大部分標準查詢參數,但 userIpcallback 參數除外。

以下範例比較 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 時,都會在回應中取得對應的報告

報表

第 4 版報表有三個頂層欄位:columnHeaderdatanextPageToken

由於 v3 回應的情況與 v3 回應不同,v4 回應主體不會納入所有查詢參數的回應,因此用戶端應用程式必須將這個參數新增至 ReportRequest

我們已處理 Pagination 區段中的 nextPageToken,因此先查看 columnHeader 物件。

欄標題

資料欄標頭包含已命名 dimensionsMetricHeader 物件的清單,該物件包含 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 陣列中傳回報表資料,其中包含要求的維度和指標。

Analytics Reporting API v4 會在 ReportRow 物件中傳回報表資料,該物件包含 dimensions 的陣列和 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 會傳回 samplesReadCountssamplingSpaceSizes 欄位。如果結果沒有取樣,系統就不會定義這些欄位。以下 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));
        }
      }
    }
  }
}

處理錯誤

由於 v4 中的錯誤回應格式與 v3 中的格式不同,請更新程式碼來處理 v4 錯誤回應。

以下範例比較第 3 版的錯誤回應和 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.\" }"
   }
  ]
 }
}