資料存取報表

您可以使用 Admin API v1 runAccessReport 方法建立資料存取報表。這份報表會顯示使用者每次讀取 Google Analytics 資料的時間。資料存取記錄最多會保留 2 年。只有具備「管理員」角色的使用者，才能存取資料存取權報告。

使用用戶端程式庫要求資料存取報告

如要快速開始使用資料存取報表，最簡單的方式就是使用用戶端程式庫。

請參閱快速入門指南，瞭解如何安裝及設定 Google Analytics 用戶端程式庫。

以下範例使用 Python 用戶端程式庫執行資料存取查詢，並列印回應。

Python

google-analytics-admin/properties_run_access_report.py
在 Cloud Shell 中開啟 前往 GitHub 查看 
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}")

與核心報表共用的功能

資料存取報表要求與許多常見功能的核心報表要求具有相同的語意。舉例來說，兩種報表類型中的分頁、維度篩選器和日期範圍行為相同。

請先參閱 Data API v1 的核心報表總覽，然後返回這個頁面，進一步瞭解資料存取報表。

建立資料存取報表

使用 runAccessReport 方法要求資料存取報告。

選取報表實體

與 Data API v1 的核心報表功能類似，Google Analytics Admin API v1 的 runAccessReport 方法也需要在網址要求路徑中指定 Google Analytics 資源 ID，格式為 properties/GA_PROPERTY_ID，例如：

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

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

如果您使用Admin API 用戶端程式庫，則不需要手動操控要求網址路徑。大多數 API 用戶端都會提供 property 參數，並預期字串格式為 properties/GA_PROPERTY_ID。如需使用用戶端程式庫的範例，請參閱本頁開頭的程式碼片段。

選擇維度和指標

維度 用於描述及分組資源的存取資料。舉例來說，維度 userEmail 會指出存取報表資料的使用者電子郵件地址。報表回應中的維度值是字串。

指標 代表報表的量化評估資料。「accessCount」指標會傳回資料存取記錄總數。

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

索取報告

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

  • dateRanges 欄位中至少須有一個有效項目。
  • dimensions 欄位中至少要有一個有效項目。
  • 如果未使用 epochTimeMicros 維度，則 metrics 欄位中至少要有一個有效項目，才能在報表中取得每個維度值組合的量化資料。

以下是包含建議欄位的要求範例。這項查詢會產生使用者電子郵件地址清單、使用者在過去 7 天內存取指定資源的最近時間，以及相應的存取次數。

HTTP

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

閱讀回覆

資料存取報表回應主要由標頭和資料列組成。標頭包含 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 位址。

HTTP

POST https://analyticsadmin.googleapis.com/v1beta/properties/GA_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 次的使用者，以及他們的電子郵件和存取次數。

HTTP

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

範例報表

您可以試試以下範例報表。

最近存取時間

以下是可使用 runAccessReport 建立的存取權報表示例：

最近一次存取的 Unix Epoch 時間 (以微秒為單位) 使用者電子郵件地址 存取次數
1525220215025371 Bola@example.net 5
1525220215028361 Alex@example.net 36
1525220215027671 Charlie@example.net 1153
1525220215027341 Mahan@example.net 1

如要產生這份報表，請查詢維度 mostRecentAccessEpochTimeMicros、userEmail和 accessCount 指標。報表會為每位使用者各提供一個資料列：mostRecentAccessEpochTimeMicros 維度會匯總每位存取資源的使用者的資料存取記錄，並為每個資料列傳回上次存取時間 (以 Unix 微秒為單位，自紀元開始計算)。

使用者存取權明細

另一個實用報表的例子是依存取機制 (例如 Google Analytics 使用者介面、API 等) 細分使用者存取權。

最近一次存取的 Unix Epoch 時間 (以微秒為單位) 使用者電子郵件地址 存取機制 存取次數
1525220215028367 Alex@example.net Firebase 31
1525220215555778 Alex@example.net Google Analytics 使用者介面 1
1525220215022378 Bola@example.net Google Analytics 使用者介面 65
1525220215026389 Bola@example.net Google Analytics API 894
1525220215025631 Charlie@example.net Google Analytics API 67
1525220215068325 Mahan@example.net Google Ads 3

如要產生這份報表，請查詢維度 mostRecentAccessEpochTimeMicros、userEmail、accessMechanism 和accessCount 指標。

這份報表會針對每位使用者/存取機制組合提供一個資料列。mostRecentAccessEpochTimeMicros 維度包含使用者上次透過指定存取機制存取資源的時間。

資源存取權總覽

您可以為資源產生報表，而不必細分個別使用者。舉例來說，下列報表會說明使用不同存取機制存取資源的頻率：

存取的資源 ID 存取的資源名稱 存取機制 存取次數
12345678 DemoApp Firebase 31
12345678 DemoApp Google Analytics 使用者介面 624
12345678 DemoApp Google Ads 83
12345678 DemoApp Google Analytics API 1744

如要產生這份報表，請查詢維度 accessedPropertyId、accessedPropertyName、accessMechanism 和accessCount 指標。

報表中的每一列都代表一組資源 ID/存取機制。

個別資料存取權

如要產生報表，讓每個資料列都以個別資料存取記錄為準，請從查詢中省略 mostRecentAccessEpochTimeMicros 維度，改用 epochTimeMicros 維度。報表的每一列都包含單一資料存取事件的相關資訊，因此不必查詢 accessCount 指標。

這份報表詳細列出使用者每次存取指定資源的相關資訊。

Unix Epoch 時間 (以微秒為單位) 使用者電子郵件地址 存取的資源 ID 存取的資源名稱 使用者 IP 存取機制 傳回的費用資料 傳回的收益資料
1525220215025371 Bola@example.net 12345678 DemoApp 1.2.3.1 Google Analytics 使用者介面 true true
1525220645645645 Mahan@example.net 12345678 DemoApp 1.2.3.5 Google Analytics 使用者介面 false false
1525220211312322 Bola@example.net 12345678 DemoApp 11.22.33.11 Google Ads true false
1525220210234221 Alex@example.net 12345678 DemoApp 11.22.33.22 Firebase false false
1525220215028368 Alex@example.net 12345678 DemoApp 1.2.3.2 Google Ads false false
1525220214234231 Mahan@example.net 12345678 DemoApp 11.22.33.55 Google Ads true true
1525220423423452 Charlie@example.net 12345678 DemoApp 1.2.3.3 Google Analytics API true false
1525220132312333 Mahan@example.net 12345678 DemoApp 1.2.3.5 Google Ads true true

如要產生這份報表，請查詢維度 epochTimeMicros、userEmail、accessedPropertyId、accessedPropertyName、userIP、accessMechanism、costDataReturned、revenueDataReturned。