概要

Google アナリティクス Admin API v1 では、runAccessReport メソッドを使用してデータアクセス レポートを生成できます。このレポートでは、ユーザーが Google アナリティクスのレポートデータを読み取るたびに記録されています。アクセス レコードは最大 2 年間保持されます。データアクセス レポートは、管理者ロールを持つユーザーのみが利用できます。

データアクセス レポートの作成

データアクセス レポートは、runAccessReport メソッドで提供されます。

コアレポートとの共有機能

多くの共有機能で、データアクセス レポート リクエストのセマンティクスはコアレポート リクエストと同じです。たとえば、ページネーション、ディメンション フィルタ、期間の仕様は、データアクセス レポートではコアレポートと同じように動作します。

Data API v1 のコアレポート機能の概要を理解します。このドキュメントの以降の部分では、データアクセス レポート リクエストに固有の機能に焦点を当てます。

報告エンティティの選択

Data API v1 のコアレポート機能と同様に、Google Analytics Admin API v1 の runAccessReport メソッドでは、Google アナリティクス 4 プロパティ識別子を properties/GA4_PROPERTY_ID の形式で URL リクエストパス内に指定する必要があります。次に例を示します。

  POST  https://analyticsadmin.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runAccessReport

結果のデータアクセス レポートは、指定した Google アナリティクス 4 プロパティの Google アナリティクスのデータアクセス レコードに基づいて生成されます。

Admin API クライアント ライブラリのいずれかを使用している場合は、リクエスト URL パスを手動で操作する必要はありません。ほとんどの API クライアントでは、文字列が properties/GA4_PROPERTY_ID の形式の property パラメータが提供されています。クライアント ライブラリの使用例については、このガイドの最後にあるコード スニペットをご覧ください。

ディメンションと指標

ディメンションは、プロパティのアクセスデータを表します。たとえば、ディメンション userEmail は、レポートデータにアクセスしたユーザーのメールアドレスを示します。レポートのレスポンスのディメンション値は文字列です。

指標は、レポートの定量的測定値を表します。accessCount 指標は、データアクセス レコードの合計数を返します。

データアクセス レポート リクエストで使用できるディメンションと指標の名前の一覧については、データアクセス スキーマをご覧ください。

データアクセス レポート リクエスト

データアクセス レポートをリクエストするには、RunAccessReportRequest オブジェクトを作成します。まずは以下のリクエスト パラメータから始めることをおすすめします。

• 期間フィールドに 1 つ以上の有効なエントリが指定されている。
• ディメンション フィールドに有効なエントリが 1 つ以上ある。
• epochTimeMicros ディメンションを使用しない場合は、metrics フィールドに有効なエントリを 1 つ以上指定し、レポートのディメンション値の組み合わせごとに定量データを取得できるようにします。

推奨フィールドを含むサンプル リクエストを次に示します。このクエリは、ユーザーのメールアドレス、過去 7 日間に指定されたプロパティに最後にアクセスした時刻、対応するアクセス数のリストを生成します。

POST https://analyticsadmin.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runAccessReport
{
  "dateRanges": [
    {
      "startDate": "7daysAgo",
      "endDate": "today"
    }
  ],
  "dimensions": [
    {
      "dimensionName": "mostRecentAccessEpochTimeMicros"
    },
    {
      "dimensionName": "userEmail"
    }
  ],
  "metrics": [
    {
      "metricName": "accessCount"
    }
  ]
}

回答を報告

概念的には、Data API v1 のコアレポート機能と同様に、アクセス レポート リクエストのデータアクセス レポート レスポンスは主にヘッダーと行です。ヘッダーは、レポート内の列をリストする AccessDimensionHeaders と AccessMetricHeaders で構成されます。

アクセス レポート行は、レポートの列の AccessDimensionValues と AccessMetricValues で構成されます。列の順序は、リクエスト、ヘッダー、すべての行で一貫しています。

上記のサンプル リクエストに対するレスポンスの例を次に示します。

{
  "dimensionHeaders": [
    {
      "dimensionName": "mostRecentAccessEpochTimeMicros"
    },
    {
      "dimensionName": "userEmail"
    }
  ],
  "metricHeaders": [
    {
      "metricName": "accessCount"
    }
  ],
  "rows": [
    {
      "dimensionValues": [
        {
          "value": "1667591408427733"
        },
        {
          "value": "Bola@example.net"
        }
      ],
      "metricValues": [
        {
          "value": "1238"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1667710959827161"
        },
        {
          "value": "Alex@example.net"
        }
      ],
      "metricValues": [
        {
          "value": "475"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1667868650762743"
        },
        {
          "value": "Mahan@example.net"
        }
      ],
      "metricValues": [
        {
          "value": "96"
        }
      ]
    }
  ],
  "rowCount": 3
}

アクセス レコードのフィルタリング

RunAccessReportRequest オブジェクトの dimensionFilter フィールドを使用して、フィルタに一致する特定のディメンション値にレポート レスポンスを制限します。

次の例では、メールアドレスが Alex@example.net である 1 人のユーザーのアクセス レコードでフィルタリングし、個々のデータアクセス レコードに基づいてレポートを生成します。このレポートには、各アクセス レコードの時刻、ユーザーのメールアドレス、IP アドレスが含まれます。

POST https://analyticsadmin.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runAccessReport
{
  "dateRanges": [
    {
      "startDate": "7daysAgo",
      "endDate": "today"
    }
  ],
  "dimensions": [
    {
      "dimensionName": "epochTimeMicros"
    },
    {
      "dimensionName": "userEmail"
    },
    {
      "dimensionName": "userIP"
    }
  ],
  "dimensionFilter": {
    "accessFilter": {
      "fieldName": "userEmail",
      "stringFilter": {
        "matchType": "EXACT",
        "value": "Alex@example.net"
      }
    }
  }
}

同様に、RunAccessReportRequest オブジェクトの metricFilter フィールドを使用すると、レポートのレスポンスをフィルタに一致する特定の指標値に制限できます。

次の例では、指定されたプロパティに 100 回以上アクセスしたすべてのユーザーのメールアドレスとアクセス数を含むレポートを生成します。

{
  "dateRanges": [
    {
      "startDate": "7daysAgo",
      "endDate": "today"
    }
  ],
  "dimensions": [
    {
      "dimensionName": "userEmail"
    }
  ],
  "metricFilter": {
    "accessFilter": {
      "numericFilter": {
        "operation": "GREATER_THAN",
        "value": {
          "int64Value": 100
        }
      },
      "fieldName": "accessCount"
    }
  },
  "metrics": [
    {
      "metricName": "accessCount"
    }
  ]
}

サンプル レポート

たとえば、次のようなサンプラー レポートを試すことができます。

ユーザーごとの最新アクセス数レポート

runAccessReport を使用して作成できる次のサンプル アクセス レポートです。

このレポートは、ディメンション mostRecentAccessEpochTimeMicros、userEmail、accessCount 指標をクエリして生成できます。レポートにはユーザーごとに 1 行が含まれます。mostRecentAccessEpochTimeMicros ディメンションは、プロパティにアクセスする各ユーザーのデータアクセス レコードを集計し、各行の最終アクセス日時（エポックからの Unix マイクロ秒）を返します。

ユーザー アクセスの内訳レポート

便利なレポートのもう一つの例として、アクセス メカニズム（Google アナリティクスのユーザー インターフェース、API など）別のユーザー アクセスの内訳があります。

このレポートは、ディメンション mostRecentAccessEpochTimeMicros、userEmail、accessMechanism、accessCount 指標をクエリして生成できます。

レポートには、ユーザーとアクセス メカニズムの組み合わせごとに 1 行が表示されます。mostRecentAccessEpochTimeMicros ディメンションには、ユーザーが指定されたアクセス メカニズムを使用してプロパティに最後にアクセスした時刻が含まれます。

プロパティ アクセスの概要レポート

個々のユーザーを分割することなく、プロパティのレポートを生成できます。たとえば、次のレポートは、さまざまなアクセス メカニズムを使用してプロパティにアクセスする頻度を示しています。

このレポートは、ディメンション accessedPropertyId、accessedPropertyName、accessMechanism、accessCount 指標をクエリして生成できます。

レポートには、プロパティ ID とアクセス メカニズムの組み合わせごとに 1 行が表示されます。

個々のデータアクセス レポート

各行が個々のデータアクセス レコードに基づくレポートを生成するには、クエリから mostRecentAccessEpochTimeMicros ディメンションを省略し、代わりに epochTimeMicros ディメンションを使用します。レポートの各行には 1 回のデータアクセスの発生に関する情報が含まれているため、accessCount 指標をクエリする必要はありません。

次のレポートには、指定したプロパティにユーザーがアクセスするたびに詳細情報が表示されます。

このレポートは、ディメンション epochTimeMicros、userEmail、accessedPropertyId、accessedPropertyName、userIP、accessMechanism、costDataReturned、revenueDataReturned をクエリして生成できます。

クライアント ライブラリ

クライアント ライブラリをインストールして構成する方法については、クイック スタートガイドをご覧ください。

Python クライアント ライブラリを使用してデータアクセス クエリを実行し、レスポンスを出力する例を次に示します。

from datetime import datetime

from google.analytics.admin import AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import (
    AccessDateRange,
    AccessDimension,
    AccessMetric,
    RunAccessReportRequest,
)


def run_sample():
    """Runs the sample."""
    # TODO(developer): Replace this variable with your Google Analytics 4
    #  property ID (e.g. "123456") before running the sample.
    property_id = "YOUR-GA4-PROPERTY-ID"
    run_access_report(property_id)


def run_access_report(property_id: str, transport: str = None):
    """
    Runs an access report for a Google Analytics property. The report will
    aggregate over dimensions `userEmail`, `accessedPropertyId`,
    `reportType`, `revenueDataReturned`, `costDataReturned`,
    `userIP`, and return the access count, as well as the most recent access
    time for each combination.
    See https://developers.google.com/analytics/devguides/config/admin/v1/access-api-schema
    for the description of each field used in a data access report query.
    Args:
        property_id(str): The Google Analytics Property ID.
        transport(str): The transport to use. For example, "grpc"
            or "rest". If set to None, a transport is chosen automatically.
    """
    client = AnalyticsAdminServiceClient(transport=transport)
    request = RunAccessReportRequest(
        entity=f"properties/{property_id}",
        dimensions=[
            AccessDimension(dimension_name="userEmail"),
            AccessDimension(dimension_name="accessedPropertyId"),
            AccessDimension(dimension_name="reportType"),
            AccessDimension(dimension_name="revenueDataReturned"),
            AccessDimension(dimension_name="costDataReturned"),
            AccessDimension(dimension_name="userIP"),
            AccessDimension(dimension_name="mostRecentAccessEpochTimeMicros"),
        ],
        metrics=[AccessMetric(metric_name="accessCount")],
        date_ranges=[AccessDateRange(start_date="yesterday", end_date="today")],
    )

    access_report = client.run_access_report(request)

    print("Result:")
    print_access_report(access_report)


def print_access_report(response):
    """Prints the access report."""
    print(f"{response.row_count} rows received")
    for dimensionHeader in response.dimension_headers:
        print(f"Dimension header name: {dimensionHeader.dimension_name}")
    for metricHeader in response.metric_headers:
        print(f"Metric header name: {metricHeader.metric_name})")

    for rowIdx, row in enumerate(response.rows):
        print(f"\nRow {rowIdx}")
        for i, dimension_value in enumerate(row.dimension_values):
            dimension_name = response.dimension_headers[i].dimension_name
            if dimension_name.endswith("Micros"):
                # Convert microseconds since Unix Epoch to datetime object.
                dimension_value_formatted = datetime.utcfromtimestamp(
                    int(dimension_value.value) / 1000000
                )
            else:
                dimension_value_formatted = dimension_value.value
            print(f"{dimension_name}: {dimension_value_formatted}")

        for i, metric_value in enumerate(row.metric_values):
            metric_name = response.metric_headers[i].metric_name
            print(f"{metric_name}: {metric_value.value}")

properties_run_access_report.py