標準のユニバーサルアナリティクス（UA）プロパティでは、2023 年 7 月 1 日をもってデータの処理が停止されました。UA 360 プロパティでは、2024 年 7 月 1 日をもってデータの処理が停止されます。また、Google アナリティクス 4 への移行に伴い、一部の UA 360 の機能はその前にサポート終了となります。Data API を使用して、GA4 プロパティのレポート機能にアクセスします。

このページは 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 アナリティクス 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

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 発見サービスを利用するその他のクライアントライブラリを使用している場合は、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 パラメータは、Metric オブジェクトのリストを受け取る 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 パラメータは、Dimension オブジェクトのリストを受け取る 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 フィールドに対応し、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 では、v3 API の標準クエリパラメータのほとんど（userIp パラメータと callback パラメータを除く）がサポートされています。

次の例では、v3 リクエストの quotaUser パラメータと 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 オブジェクトのリストが含まれています。各 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 オブジェクトの配列が含まれます。各オブジェクトには 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 は、true に設定されたブール値フィールド containsSampledData を返します。

データがサンプリングされた場合、アナリティクス 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.\" }"
   }
  ]
 }
}

移行ガイド

はじめに

Python の移行

エンドポイント

v3 のエンドポイント

v4 のエンドポイント

v3

v4

クライアント ライブラリおよび発見サービス

Python

JavaScript

リクエスト

ビュー ID

v3

v4

期間

v3

v4

指標

v3

v4

ディメンション

v3

v4

並べ替え

v3

v4

サンプリング レベル

v3

v4

セグメント

セグメント ID

v3

v4

動的セグメント

v3

v4

v3

v4

v4 における v3 セグメント構文

v3

v4

フィルタ

v3

v4

v4 における v3 フィルタ構文

v3

v4

空の行

v3

v4

ページネーション

v3

v4

標準パラメータ

v3 のエンドポイント

v4 のエンドポイント

レスポンス

レポート

列ヘッダー

v3

v4

レポートの行

行

v3

v4

サンプルデータ

v4 レスポンスの解析

Python

Java

エラー処理

v3

v4

クライアントライブラリおよび発見サービス

サンプリングレベル