API Quản trị của Google Analytics phiên bản 1 cho phép bạn tạo báo cáo về quyền truy cập dữ liệu bằng phương thức runAccessReport
. Báo cáo này cung cấp bản ghi mỗi lần người dùng đọc dữ liệu báo cáo của Google
Analytics. Bản ghi quyền truy cập sẽ được lưu giữ trong tối đa 2 năm.
Báo cáo Truy cập dữ liệu chỉ được cung cấp cho người dùng có vai trò Quản trị viên.
Tạo báo cáo quyền truy cập dữ liệu
Báo cáo Quyền truy cập dữ liệu được cung cấp bằng phương thức runAccessReport.
Các tính năng được chia sẻ với báo cáo chính
Các yêu cầu báo cáo Truy cập dữ liệu có cùng ngữ nghĩa với các yêu cầu báo cáo chính, cho nhiều tính năng dùng chung. Ví dụ: Phân trang, Bộ lọc thứ nguyên, quy cách Phạm vi ngày hoạt động giống như trong Báo cáo truy cập dữ liệu dưới dạng Báo cáo chính.
Hãy làm quen với Tổng quan về chức năng Báo cáo chính của Data API phiên bản 1, vì phần còn lại của tài liệu này sẽ tập trung vào các tính năng dành riêng cho các yêu cầu báo cáo Truy cập dữ liệu.
Chọn đối tượng báo cáo
Tương tự như Chức năng báo cáo chính
của API Dữ liệu phiên bản 1, phương thức runAccessReport
của API Quản trị Google Analytics phiên bản 1 yêu cầu
giá trị nhận dạng tài sản Google Analytics 4
phải được chỉ định trong đường dẫn yêu cầu URL ở dạng
properties/GA4_PROPERTY_ID
, chẳng hạn như:
POST https://analyticsadmin.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runAccessReport
Báo cáo về quyền truy cập dữ liệu thu được sẽ được tạo dựa trên các bản ghi về quyền truy cập dữ liệu Google Analytics cho tài sản Google Analytics 4 được chỉ định.
Nếu đang sử dụng một trong những thư viện ứng dụng của API Quản trị, bạn không cần phải chỉnh sửa đường dẫn URL yêu cầu theo cách thủ công. Hầu hết các ứng dụng API đều cung cấp tham số property
dự kiến sẽ có một chuỗi ở dạng properties/GA4_PROPERTY_ID
. Hãy xem đoạn mã ở cuối hướng dẫn này để biết ví dụ về cách sử dụng thư viện ứng dụng.
Thứ nguyên và chỉ số
Phương diện mô tả và nhóm dữ liệu về quyền truy cập cho tài sản của bạn. Ví dụ: phương diện userEmail
cho biết email của người dùng đã truy cập vào dữ liệu báo cáo.
Giá trị phương diện trong phản hồi báo cáo là chuỗi.
Chỉ số đại diện cho các phép đo định lượng của một báo cáo. Chỉ số accessCount
trả về tổng số bản ghi truy cập dữ liệu.
Hãy xem Giản đồ truy cập dữ liệu để biết danh sách đầy đủ tên phương diện và chỉ số có trong các yêu cầu báo cáo truy cập dữ liệu.
Yêu cầu báo cáo quyền truy cập dữ liệu
Để yêu cầu báo cáo về quyền truy cập dữ liệu, hãy tạo đối tượng RunAccessReportRequest. Bạn nên bắt đầu với các tham số yêu cầu sau:
- Ít nhất một mục nhập hợp lệ trong trường phạm vi ngày.
- Ít nhất một mục nhập hợp lệ trong trường phương diện.
- Nếu không sử dụng phương diện
epochTimeMicros
, hãy có ít nhất một mục nhập hợp lệ trong trường metrics để nhận dữ liệu định lượng cho mỗi tổ hợp giá trị phương diện trong một báo cáo.
Dưới đây là một yêu cầu mẫu chứa các trường đề xuất. Truy vấn này sẽ tạo ra một danh sách email của người dùng, lần gần đây nhất họ truy cập vào thuộc tính đã chỉ định trong phạm vi 7 ngày qua và số lượt truy cập tương ứng.
HTTP
POST https://analyticsadmin.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runAccessReport
{
"dateRanges": [
{
"startDate": "7daysAgo",
"endDate": "today"
}
],
"dimensions": [
{
"dimensionName": "mostRecentAccessEpochTimeMicros"
},
{
"dimensionName": "userEmail"
}
],
"metrics": [
{
"metricName": "accessCount"
}
]
}
Phản hồi báo cáo
Về mặt lý thuyết, tương tự như chức năng báo cáo chính của Data API phiên bản 1, Phản hồi báo cáo quyền truy cập dữ liệu của yêu cầu báo cáo quyền truy cập chủ yếu là một tiêu đề và các hàng. Tiêu đề bao gồm AccessDimensionHeaders
và AccessMetricHeaders
liệt kê các cột trong Báo cáo.
Mỗi hàng báo cáo quyền truy cập bao gồm AccessDimensionValues
và AccessMetricValues
cho các cột trong báo cáo. Thứ tự của các cột trong yêu cầu, tiêu đề và mọi hàng đều phải nhất quán.
Dưới đây là phản hồi mẫu cho yêu cầu mẫu trước đó:
{
"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
}
Lọc trên bản ghi truy cập
Sử dụng trường dimensionFilter của đối tượng RunAccessReportRequest để hạn chế phản hồi báo cáo cho những giá trị phương diện cụ thể khớp với bộ lọc.
Ví dụ sau đây sẽ tạo một báo cáo dựa trên các bản ghi quyền truy cập dữ liệu cá nhân, lọc ra bản ghi truy cập của một người dùng có email Alex@example.net
. Báo cáo này chứa thời gian của mỗi bản ghi truy cập, email và địa chỉ IP của người dùng.
HTTP
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"
}
}
}
}
Tương tự, bạn có thể dùng trường metricFilter
của đối tượng RunAccessReportRequest
để hạn chế phản hồi báo cáo theo các giá trị chỉ số cụ thể khớp với bộ lọc.
Ví dụ sau đây tạo một báo cáo chứa email và số lượt truy cập của tất cả người dùng đã truy cập vào tài sản được chỉ định hơn 100 lần.
HTTP
{
"dateRanges": [
{
"startDate": "7daysAgo",
"endDate": "today"
}
],
"dimensions": [
{
"dimensionName": "userEmail"
}
],
"metricFilter": {
"accessFilter": {
"numericFilter": {
"operation": "GREATER_THAN",
"value": {
"int64Value": 100
}
},
"fieldName": "accessCount"
}
},
"metrics": [
{
"metricName": "accessCount"
}
]
}
Báo cáo mẫu
Dưới đây là một số báo cáo mẫu mà bạn có thể thử.
Báo cáo về số lần truy cập gần đây nhất của mỗi người dùng
Bạn có thể tạo báo cáo quyền truy cập mẫu sau đây bằng runAccessReport
:
Thời gian truy cập gần đây nhất (Epoch Time Micros) | Email người dùng | Số lượt truy cập |
---|---|---|
1525220215025371 | Bola@example.net | 5 |
1525220215028361 | Alex@example.net | 36 |
1525220215027671 | Charlie@example.net | 1153 |
1525220215027341 | Mahan@example.net | 1 |
Có thể tạo báo cáo này bằng cách truy vấn các phương diện
mostRecentAccessEpochTimeMicros
, userEmail
và accessCount
chỉ số. Báo cáo này chứa một hàng cho mỗi người dùng: phương diện mostRecentAccessEpochTimeMicros
tổng hợp các bản ghi quyền truy cập dữ liệu của mỗi người dùng truy cập vào tài sản và trả về thời gian truy cập gần đây nhất (tính bằng micrô giây Unix kể từ thời gian bắt đầu của hệ thống) cho mỗi hàng.
Báo cáo chi tiết về quyền truy cập của người dùng
Một ví dụ khác về báo cáo hữu ích là bảng phân tích lượt truy cập của người dùng theo Cơ chế truy cập (ví dụ: Giao diện người dùng Google Analytics, API, v.v.).
Thời gian truy cập gần đây nhất (Epoch Time Micros) | Email người dùng | Cơ chế truy cập | Số lượt truy cập |
---|---|---|---|
1525220215028367 | Alex@example.net | Firebase | 31 |
1525220215555778 | Alex@example.net | Giao diện người dùng Google Analytics | 1 |
1525220215022378 | Bola@example.net | Giao diện người dùng Google Analytics | 65 |
1525220215026389 | Bola@example.net | API Google Analytics | 894 |
1525220215025631 | Charlie@example.net | API Google Analytics | 67 |
1525220215068325 | Mahan@example.net | Google Ads | 3 |
Bạn có thể tạo báo cáo này bằng cách truy vấn các phương diện
mostRecentAccessEpochTimeMicros
, userEmail
, accessMechanism
và
accessCount
chỉ số.
Báo cáo chứa một hàng cho mỗi tổ hợp người dùng/cơ chế truy cập. Phương diện
mostRecentAccessEpochTimeMicros
chứa lần gần nhất người dùng
truy cập vào thuộc tính bằng Cơ chế truy cập được chỉ định.
Báo cáo tổng quan về quyền truy cập vào tài sản
Bạn có thể tạo báo cáo cho một tài sản mà không cần phân tích chi tiết về từng người dùng. Ví dụ: báo cáo sau đây cho biết tần suất truy cập vào một tài sản thông qua Cơ chế truy cập khác nhau:
Mã thuộc tính đã truy cập | Tên thuộc tính được truy cập | Cơ chế truy cập | Số lượt truy cập |
---|---|---|---|
12345678 | DemoApp | Firebase | 31 |
12345678 | DemoApp | Giao diện người dùng Google Analytics | 624 |
12345678 | DemoApp | Google Ads | 83 |
12345678 | DemoApp | API Google Analytics | 1744 |
Bạn có thể tạo báo cáo này bằng cách truy vấn phương diện accessedPropertyId
, accessedPropertyName
, accessMechanism
và chỉ số accessCount
.
Báo cáo này có một hàng cho mỗi tổ hợp mã tài sản/cơ chế truy cập.
Báo cáo về từng lượt truy cập vào dữ liệu
Để tạo báo cáo mà mỗi hàng dựa trên một bản ghi truy cập dữ liệu riêng lẻ, hãy bỏ phương diện mostRecentAccessEpochTimeMicros
khỏi truy vấn và sử dụng phương diện epochTimeMicros
. Bạn không cần truy vấn chỉ số accessCount
, vì mỗi hàng của báo cáo đều chứa thông tin về một lần truy cập dữ liệu.
Báo cáo sau đây chứa thông tin chi tiết về mỗi lần người dùng truy cập vào thuộc tính được chỉ định.
Epoch Time Micros | Email người dùng | Mã thuộc tính đã truy cập | Tên thuộc tính được truy cập | IP người dùng | Cơ chế truy cập | Dữ liệu chi phí đã trả về | Đã trả lại dữ liệu doanh thu |
---|---|---|---|---|---|---|---|
1525220215025371 | Bola@example.net | 12345678 | DemoApp | 1.2.3.1 | Giao diện người dùng Google Analytics | đúng | đúng |
1525220645645645 | Mahan@example.net | 12345678 | DemoApp | 1.2.3.5 | Giao diện người dùng Google Analytics | false | false |
1525220211312322 | Bola@example.net | 12345678 | DemoApp | 11.22.33.11 | Google Ads | đúng | 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 | đúng | đúng |
1525220423423452 | Charlie@example.net | 12345678 | DemoApp | 1.2.3.3 | API Google Analytics | đúng | false |
1525220132312333 | Mahan@example.net | 12345678 | DemoApp | 1.2.3.5 | Google Ads | đúng | đúng |
Bạn có thể tạo báo cáo này bằng cách truy vấn các phương diện
epochTimeMicros
, userEmail
, accessedPropertyId
, accessedPropertyName
,
userIP
, accessMechanism
, costDataReturned
, revenueDataReturned
.
Thư viện ứng dụng
Hãy xem Hướng dẫn bắt đầu nhanh để được giải thích về cách cài đặt và định cấu hình thư viện ứng dụng.
Dưới đây là một ví dụ về cách sử dụng thư viện ứng dụng Python chạy một truy vấn truy cập dữ liệu và in phản hồi.
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}")