Tổng quan

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

google-analytics-admin/properties_run_access_report.py
Mở trong Cloud Shell Xem trên 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