ภาพรวม

Google Analytics Admin API v1 ช่วยให้คุณสร้างรายงานการเข้าถึงข้อมูลได้โดยใช้เมธอด runAccessReport รายงานจะแสดงบันทึกในแต่ละครั้งที่ผู้ใช้อ่านข้อมูลการรายงานของ Google Analytics ระบบจะเก็บรักษาบันทึกการเข้าถึงไว้ไม่เกิน 2 ปี ผู้ใช้ที่มีบทบาทผู้ดูแลระบบเท่านั้นที่สามารถใช้รายงานการเข้าถึงข้อมูลได้

การสร้างรายงานการเข้าถึงข้อมูล

การรายงานการเข้าถึงข้อมูลสามารถทำได้โดยเมธอด runAccessReport

ฟีเจอร์ที่แชร์กับรายงานหลัก

คำขอรายงานการเข้าถึงข้อมูลมีความหมายเดียวกันกับคำขอรายงานหลักสำหรับฟีเจอร์ที่ใช้ร่วมกันหลายรายการ ตัวอย่างเช่น การใส่เลขหน้า ตัวกรองมิติข้อมูล ข้อกำหนดเกี่ยวกับช่วงวันที่ จะทำงานเหมือนกับรายงานหลักในรายงานการเข้าถึงข้อมูล

ทำความคุ้นเคยกับ ภาพรวมของฟังก์ชันการรายงานหลักของ Data API v1 เพราะส่วนที่เหลือของเอกสารนี้จะเน้นไปที่คุณลักษณะที่มีเฉพาะใน คำขอรายงานการเข้าถึงข้อมูล

การเลือกเอนทิตีการรายงาน

เช่นเดียวกับฟังก์ชันการรายงานหลักของ Data API v1 เมธอด runAccessReport ของ Google Analytics Admin API v1 กำหนดให้ระบุตัวระบุพร็อพเพอร์ตี้ Google Analytics 4 ภายในเส้นทางคำขอ URL ในรูปแบบ properties/GA4_PROPERTY_ID เช่น

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

ระบบจะสร้างรายงานการเข้าถึงข้อมูลที่ได้โดยอิงตามบันทึกการเข้าถึงข้อมูล Google Analytics สําหรับพร็อพเพอร์ตี้ Google Analytics 4 ที่ระบุ

หากใช้ไลบรารีของไคลเอ็นต์ Admin API แบบใดแบบหนึ่งอยู่ คุณไม่จำเป็นต้องจัดการเส้นทาง URL คำขอด้วยตนเอง ไคลเอ็นต์ API ส่วนใหญ่จะมีพารามิเตอร์ property ที่คาดหวังสตริงในรูปแบบ properties/GA4_PROPERTY_ID ดูข้อมูลโค้ดที่ท้ายคู่มือนี้เพื่อดูตัวอย่างการใช้ไลบรารีของไคลเอ็นต์

มิติข้อมูลและเมตริก

มิติข้อมูล อธิบายและจัดกลุ่มข้อมูลพร็อพเพอร์ตี้ของคุณ ตัวอย่างเช่น มิติข้อมูล userEmail จะระบุอีเมลของผู้ใช้ที่เข้าถึงข้อมูลการรายงาน ค่ามิติข้อมูลในการตอบกลับรายงานเป็นสตริง

เมตริก แสดงถึงการวัดเชิงปริมาณของรายงาน เมตริก accessCount จะแสดงผลจำนวนบันทึกการเข้าถึงข้อมูลทั้งหมด

ดูรายการชื่อมิติข้อมูลและเมตริกทั้งหมดที่มีอยู่ในคำขอรายงานการเข้าถึงข้อมูลได้ในสคีมาการเข้าถึงข้อมูล

คำขอรายงานการเข้าถึงข้อมูล

หากต้องการขอรายงานการเข้าถึงข้อมูล ให้สร้างออบเจ็กต์ RunAccessReportRequest เราขอแนะนำให้เริ่มต้นด้วยพารามิเตอร์คำขอเหล่านี้

  • ข้อมูลในช่องช่วงวันที่ที่ถูกต้องอย่างน้อย 1 รายการ
  • ข้อมูลที่ถูกต้องอย่างน้อย 1 รายการในช่องมิติข้อมูล
  • หากไม่ได้ใช้มิติข้อมูล epochTimeMicros คุณจะต้องป้อนข้อมูลที่ถูกต้องอย่างน้อย 1 รายการในช่องmetricsเพื่อรับข้อมูลเชิงปริมาณของชุดค่าผสมมิติข้อมูลแต่ละชุดในรายงาน

ต่อไปนี้เป็นคำขอตัวอย่างพร้อมฟิลด์ที่แนะนำ การค้นหานี้จะสร้างรายการอีเมลผู้ใช้ เวลาล่าสุดที่ผู้ใช้เข้าถึงพร็อพเพอร์ตี้ที่ระบุในช่วง 7 วันที่ผ่านมา และจํานวนการเข้าถึงที่เกี่ยวข้อง

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"
    }
  ]
}

รายงานคำตอบ

โดยหลักการแล้ว คล้ายกับฟังก์ชันการรายงานหลักของ 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
}

การกรองในบันทึกการเข้าถึง

ใช้ช่อง dimensionFilter ของออบเจ็กต์ RunAccessReportRequest เพื่อจำกัดการตอบกลับรายงานเป็นค่ามิติข้อมูลที่เฉพาะเจาะจงซึ่งตรงกับตัวกรอง

ตัวอย่างต่อไปนี้จะสร้างรายงานตามระเบียนการเข้าถึงข้อมูลแต่ละรายการ โดยกรองตามบันทึกการเข้าถึงของผู้ใช้รายเดียวที่มีอีเมล Alex@example.net รายงานจะมีเวลาของระเบียนการเข้าถึงแต่ละรายการ อีเมล และที่อยู่ IP ของผู้ใช้

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"
      }
    }
  }
}

ในทำนองเดียวกัน คุณสามารถใช้ช่อง 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 ได้

เวลาการเข้าถึงล่าสุดในหน่วยไมโคร อีเมลผู้ใช้ จำนวนการเข้าถึง
1525220215025371 Bola@example.net 5
1525220215028361 Alex@example.net 36
1525220215027671 Charlie@example.net 1153
1525220215027341 Mahan@example.net 1

รายงานนี้สร้างขึ้นได้โดยการค้นหามิติข้อมูล mostRecentAccessEpochTimeMicros, userEmail และ accessCount เมตริก รายงานจะมี 1 แถวต่อผู้ใช้แต่ละราย: มิติข้อมูล mostRecentAccessEpochTimeMicros จะรวบรวมบันทึกการเข้าถึงข้อมูลของผู้ใช้แต่ละรายที่เข้าถึงพร็อพเพอร์ตี้ และแสดงผลเวลาการเข้าถึงล่าสุด (เป็น Unix ไมโครวินาทีนับตั้งแต่ Epoch) สําหรับแต่ละแถว

รายงานรายละเอียดการเข้าถึงของผู้ใช้

อีกตัวอย่างหนึ่งของรายงานที่มีประโยชน์คือรายละเอียดการเข้าถึงของผู้ใช้ตามกลไกการเข้าถึง (เช่น อินเทอร์เฟซผู้ใช้ของ Google Analytics, API ฯลฯ)

เวลาการเข้าถึงล่าสุดในหน่วยไมโคร อีเมลผู้ใช้ กลไกการเข้าถึง จำนวนการเข้าถึง
1525220215028367 Alex@example.net Firebase 31
1525220215555778 Alex@example.net อินเทอร์เฟซผู้ใช้ Google Analytics 1
1525220215022378 Bola@example.net อินเทอร์เฟซผู้ใช้ 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

รายงานนี้สร้างขึ้นได้โดยการค้นหามิติข้อมูล mostRecentAccessEpochTimeMicros userEmail accessMechanism และ accessCount เมตริก

รายงานจะมีแถว 1 แถวต่อชุดค่าผสมกลไกของผู้ใช้/การเข้าถึงแต่ละชุด มิติข้อมูล mostRecentAccessEpochTimeMicros ประกอบด้วยเวลาล่าสุดที่ผู้ใช้เข้าถึงพร็อพเพอร์ตี้โดยใช้กลไกการเข้าถึงที่ระบุ

รายงานภาพรวมการเข้าถึงพร็อพเพอร์ตี้

คุณสร้างรายงานสำหรับพร็อพเพอร์ตี้ได้โดยไม่ต้องแจกแจงผู้ใช้แต่ละราย ตัวอย่างเช่น รายงานต่อไปนี้จะระบุความถี่ในการเข้าถึงพร็อพเพอร์ตี้โดยใช้กลไกการเข้าถึงต่างๆ

รหัสพร็อพเพอร์ตี้ที่มีการเข้าถึง ชื่อพร็อพเพอร์ตี้ที่เข้าถึง กลไกการเข้าถึง จำนวนการเข้าถึง
12345678 DemoApp Firebase 31
12345678 DemoApp อินเทอร์เฟซผู้ใช้ Google Analytics 624
12345678 DemoApp Google Ads 83
12345678 DemoApp API ของ Google Analytics 1744

รายงานนี้สร้างขึ้นได้โดยการค้นหาในมิติข้อมูล accessedPropertyId, accessedPropertyName, accessMechanism และaccessCount เมตริก

รายงานจะมี 1 แถวต่อชุดค่าผสมรหัสพร็อพเพอร์ตี้/การเข้าถึงแต่ละชุดของกลไกการเข้าถึง

รายงานการเข้าถึงข้อมูลแต่ละรายการ

หากต้องการสร้างรายงานที่แต่ละแถวอิงตามระเบียนการเข้าถึงข้อมูลแต่ละรายการ ให้ละเว้นมิติข้อมูล mostRecentAccessEpochTimeMicros ในการค้นหาและใช้มิติข้อมูล epochTimeMicros แทน คุณไม่จำเป็นต้องค้นหาเมตริก accessCount เนื่องจากรายงานทุกแถวจะมีข้อมูลเกี่ยวกับการเข้าถึงข้อมูลเพียงรายการเดียว

รายงานต่อไปนี้มีข้อมูลโดยละเอียดเกี่ยวกับเวลาที่ผู้ใช้เข้าถึงพร็อพเพอร์ตี้ที่ระบุในแต่ละครั้ง

Epoch Time Micros อีเมลผู้ใช้ รหัสพร็อพเพอร์ตี้ที่มีการเข้าถึง ชื่อพร็อพเพอร์ตี้ที่เข้าถึง IP ผู้ใช้ กลไกการเข้าถึง ข้อมูลค่าใช้จ่ายที่แสดงผล ข้อมูลรายได้ที่แสดงผล
1525220215025371 Bola@example.net 12345678 DemoApp 1.2.3.1 อินเทอร์เฟซผู้ใช้ Google Analytics จริง จริง
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 จริง 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 จริง จริง
1525220423423452 Charlie@example.net 12345678 DemoApp 1.2.3.3 API ของ Google Analytics จริง false
1525220132312333 Mahan@example.net 12345678 DemoApp 1.2.3.5 Google Ads จริง จริง

รายงานนี้สร้างขึ้นได้โดยการค้นหาในมิติข้อมูล 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