總覽

Google Analytics Admin API v1 可讓您以下列方式存取報表： runAccessReport 方法。報表會在使用者每次讀取 Google Analytics 時提供記錄 報表資料。存取記錄最多會保留 2 年。資料存取權 只有具備管理員角色的使用者才能使用報表。

建立資料存取報表

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

與核心報表共用的功能

「資料存取」報表要求與核心報表有相同的語意 要求處理許多共用功能。例如： 分頁、維度篩選器、日期範圍規格的運作方式相同 做為核心報表

熟悉 Google Ads 的核心報表功能 第二版 Data API v1 這份文件會著重於資料存取報表要求的專屬功能。

選取檢舉實體

與核心報表類似 主要功能 Data API v1，runAccessReport 如要使用 Google Analytics Admin API 第 1 版這個方法，必須安裝 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 物件。三 建議您先從以下要求參數著手：

  • 日期中至少有一個有效的項目 範圍 ] 欄位。
  • 在 維度 ] 欄位。
  • 如果沒有使用「epochTimeMicros」維度，則以下項目中至少有一個有效項目： 這個 指標 欄位接收每個維度值組合的量化資料 或報告

以下是包含建議欄位的要求範例。這項查詢會產生 使用者電子郵件清單，最近存取指定資源的時間 顯示最近 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"
    }
  ]
}

檢舉回應

概念與核心報表相似 資料 API 第 1 版的所有功能 資料存取報表 回應 存取報表要求主要是標題和列。標題由 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
}

篩選存取記錄

使用 dimensionFilter 欄位 RunAccessReportRequest 物件，限制報表回應只符合 篩選。

下例是根據個別資料存取權產生報表 記錄，篩選單一使用者的存取記錄 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"
      }
    }
  }
}

同樣地， metricFilter敬上 欄位 RunAccessReportRequest。 物件，可用來限制報表回應的特定指標值， 與篩選器相符

下例會產生一份報表，其中包含下列來源的電子郵件和存取計數： 所有存取指定資源超過 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 建立以下存取權報表範例：

最近一次存取 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 微秒為單位，自 Epoch 時間。

使用者存取權細目報表

另一個實用的報表範例是按「存取權」欄細分使用者存取資料 機制 (例如 Google Analytics 使用者介面、API 等)。

最近一次存取 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 metric。

在這個報表中，每組使用者/存取機制組合會自成一列。 「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 metric。

這份報表的每個資源 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。

用戶端程式庫

如需相關說明，請參閱快速入門指南 如何安裝及設定用戶端程式庫。

以下示範如何使用 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}")


properties_run_access_report.py