總覽

Google Analytics Admin API v1 可讓您使用 runAccessReport 方法產生資料存取報表。使用者每次讀取 Google Analytics (分析) 報表資料時，此報表都會提供記錄。存取記錄最多會保留 2 年。只有具備「管理員」角色的使用者才能查看資料存取報表。

建立資料存取報表

資料存取報表是由 runAccessReport 方法提供。

與核心報表共用的功能

對於許多共用功能，資料存取報表要求與核心報表要求具有相同的語意。舉例來說，分頁、維度篩選器和日期範圍規格在資料存取報表中與核心報表相同。

熟悉 Data API v1 核心報表功能總覽，但本文的其餘部分將著重於資料存取報表要求的專屬功能。

選取檢舉實體

與 Data API v1 的核心報表功能類似，Google Analytics Admin API v1 的 runAccessReport 方法需要使用 properties/GA4_PROPERTY_ID 在網址要求路徑內指定 Google Analytics (分析) 4 資源 ID，例如：

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

系統會根據指定 Google Analytics (分析) 4 資源的 Google Analytics (分析) 資料存取記錄，產生產生的資料存取報表。

如果您使用其中一個 Admin API 用戶端程式庫，則不需要手動操控要求網址路徑。多數 API 用戶端提供的 property 參數會預期字串格式為 properties/GA4_PROPERTY_ID。如需使用用戶端程式庫的範例，請參閱本指南結尾的程式碼片段。

維度和指標

維度說明及分組資源的存取權資料。舉例來說，userEmail 維度表示存取報表資料的使用者電子郵件。報表回應中的維度值是字串。

指標代表報表的量化測量結果。accessCount 指標會傳回資料存取記錄的總數。

如需資料存取報表要求中可用的維度和指標名稱的完整清單，請參閱資料存取結構定義。

資料存取報表要求

如要要求資料存取報表，請建構 RunAccessReportRequest 物件。建議您先使用以下請求參數：

• 「日期範圍」欄位中至少有一個有效項目。
• 「dimensions」欄位中至少有一個有效項目。
• 如果您不使用 epochTimeMicros 維度，則「指標」metrics欄位中至少有一個有效項目，可接收報表中每個維度值組合的量化資料。

以下是包含建議欄位的範例要求。這項查詢將產生一份使用者電子郵件清單、使用者在最近 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 的單一使用者的存取記錄。報表內含每筆存取記錄的時間、使用者電子郵件和 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 指標來產生這份報表。報表中的每個使用者都會有一列：mostRecentAccessEpochTimeMicros 維度會匯總每位使用者存取屬性的資料存取記錄，並傳回每個資料列的上次存取時間 (以 Unix 微秒為單位)。

使用者存取權明細報表

另一個實用報表的範例，是依據存取機制 (例如 Google Analytics (分析) 使用者介面、API 等) 細分使用者存取資料的情況。

系統可以查詢維度 mostRecentAccessEpochTimeMicros、userEmail、accessMechanism 和 accessCount 指標來產生這份報表。

報表會針對每個使用者/存取機制組合顯示一列。mostRecentAccessEpochTimeMicros 維度包含使用者上次透過指定存取機制存取屬性的時間。

資源存取權總覽報表

您可以在不細分個別使用者的情況下，產生資源的報告。舉例來說，以下報表說明使用不同存取機制存取資源的頻率：

系統可以查詢 維度 accessedPropertyId、accessedPropertyName、accessMechanism 和 accessCount 指標來產生這份報表。

這份報表的每個資源 ID/存取機制組合會有一列資料。

個別資料存取報表

如要產生報表，其中每個資料列都以個別資料存取記錄為依據，請在查詢中省略 mostRecentAccessEpochTimeMicros 維度，改用 epochTimeMicros 維度。您不需要查詢 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