このガイドでは、Core Reporting API v3 をアナリティクス Reporting API v4 に移行する際のガイドラインについて説明します。
はじめに
アナリティクス Reporting API v4 で導入された新しい機能を利用するには、コードを移行してこの API を使用できるようにする必要があります。 このガイドでは、移行を簡単に行えるように、Core Reporting API v3 のリクエストと、それに対応するアナリティクス Reporting API v4 のリクエストを示します。
Python の移行
Python で開発を行っている場合は、GitHub の GAV4 ヘルパー ライブラリを使用して、Google アナリティクス Core Reporting API v3 のリクエストをアナリティクス 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
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
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 発見サービスを利用するその他のクライアント ライブラリを使用している場合は、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 の場合、ビュー（旧プロファイル）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 では、1 回のリクエストで複数の期間を指定できます。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 フィールドに対応しています。このフィールドには、Metric オブジェクトのリストを指定します。
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 フィールドに対応しています。このフィールドには、Dimension オブジェクトのリストを指定します。
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 パラメータは、v4 の orderBys フィールドに対応しています。このフィールドには、OrderBy オブジェクトのリストを指定します。
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 と HIGHER_PRECISION は、v4 ではそれぞれ SMALL と 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 フィールドに対応しています。このフィールドには、Segment オブジェクトのリストを指定します。
セグメント ID
v4 の場合、セグメント ID でセグメントをリクエストするには、Segment オブジェクトを作成し、その ID を segmentId フィールドで指定します。
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" ]
}
}]
}]
}
}]
}
}
}]
}]
}
1 つのセグメントで条件とシーケンスを組み合わせることができます。
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 のセグメント構文がサポートされます。
v3 リクエストの segment パラメータが、対応する v4 リクエストの segmentId フィールドでどのようにサポートされるかを次の例で示します。
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 構文がサポートされますが、ディメンションと指標にフィルタを適用する際は、dimensionFilterClauses と metricFilterClauses を使用してください。
v3 リクエストの filters パラメータが、対応する v4 リクエストの filtersExpression フィールドでどのようにサポートされるかを次の例で示します。
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 では、userIp パラメータと callback パラメータを除く、v3 API の標準クエリ パラメータの大部分がサポートされます。
v3 リクエストと v4 リクエストの quotaUser パラメータを比較した例を次に示します。
v3 のエンドポイント
GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2
v4 のエンドポイント
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2
レスポンス
v4 では、1 回の HTTP リクエストで複数の ReportRequest オブジェクトを送信できます。そのためレスポンスでは、レポート オブジェクトの配列を取得します。ReportRequest を送信するとそのたびに、対応する Report がレスポンスで得られます。
レポート
v4 のレポートには、columnHeader、data、nextPageToken という 3 つのトップレベル フィールドがあります。
v3 のレスポンスとは異なり、v4 のレスポンス本文には、すべてのクエリ パラメータに対する応答が含まれていません。そのため、特定のクエリ パラメータのレスポンスを取得するには、クライアント アプリケーションがそのパラメータを ReportRequest に追加する必要があります。
nextPageToken についてはページ設定セクションで説明したので、最初に columnHeader オブジェクトを確認します。
列見出し
列見出しには、指定されたディメンションと MetricHeader オブジェクトのリストが含まれています。また、このオブジェクトには、 オブジェクトのリストが含まれています。各 MetricHeaderEntry オブジェクトでは、指標の name とその type（currency、percent など）を指定します。これにより、出力をフォーマットできます。
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 は、行の配列でレポートデータを返します。この配列には、リクエストされたディメンションと指標が含まれています。
アナリティクス Reporting API v4 は、ReportRow オブジェクトでレポートデータを返します。このオブジェクトには、ディメンションの配列と DateRangeValues オブジェクトの配列が含まれており、次の図に示すように、それぞれに 1 つまたは 2 つの期間が含まれています。
行
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 に設定されます）。
アナリティクス Reporting API v4 では、データがサンプリングされる場合、ブール値を返さずに、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 つの期間が指定されたリクエストからのサンプルデータを含むレスポンスの例を 次に示します。この結果は、約 1,500 万セッションのサンプリング スペース サイズのほぼ 500,000 件のサンプルから計算されました。
{
"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
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 のエラー レスポンスに対応させてください。
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.\" }"
}
]
}
}