Tổng quan

Google Analytics Data API phiên bản 1 cho phép bạn tạo bảng tổng hợp. Bảng tổng hợp là công cụ tóm tắt dữ liệu trực quan hoá dữ liệu bằng cách sắp xếp lại thông tin trong bảng bằng cách tổng hợp (xoay) dữ liệu của bạn trên một hoặc nhiều phương diện.

Ví dụ: hãy xem xét bảng dữ liệu thô sau đây:

Khi sử dụng dữ liệu này, bạn có thể tạo bảng tổng hợp, chia nhỏ dữ liệu phiên theo trình duyệt, với các phương diện quốc gia và ngôn ngữ được chọn làm bảng tổng hợp bổ sung.

Lưu ý: Để được trợ giúp về việc di chuyển mã hiện có từ API Báo cáo Google Analytics phiên bản 4 (chỉ dành cho tài sản Universal Analytics), sang Google Analytics Data API phiên bản 1 (chỉ dành cho tài sản Google Analytics 4), hãy xem Hướng dẫn di chuyển.

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 tổng hợp 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ụ: tính năng phân trang, Bộ lọc phương diện và Thuộc tính người dùng hoạt động giống như trong Báo cáo tổng hợp như Báo cáo chính. Hướng dẫn này tập trung vào các tính năng báo cáo tổng hợp. Để làm quen với chức năng Báo cáo cốt lõi của Data API phiên bản 1, hãy đọc hướng dẫn cơ bản về báo cáo cũng như hướng dẫn các trường hợp sử dụng nâng cao.

Phương pháp báo cáo tổng hợp

Data API phiên bản 1 hỗ trợ chức năng tổng hợp trong các phương thức báo cáo sau:

• runPivotReport Phương thức này trả về báo cáo tổng hợp tuỳ chỉnh về dữ liệu sự kiện của bạn trên Google Analytics. Mỗi trung tâm mô tả các hàng và cột phương diện hiển thị trong nội dung phản hồi báo cáo.

• batchRunPivotReports Đây là phiên bản hàng loạt của phương thức runPivotReport cho phép tạo nhiều báo cáo bằng một lệnh gọi API duy nhất.

Chọn đối tượng báo cáo

Tất cả các phương thức của Data API phiên bản 1 đều yêu cầu phải chỉ định giá trị nhận dạng thuộc tính Google Analytics 4 bên trong đường dẫn yêu cầu URL ở dạng properties/GA4_PROPERTY_ID, chẳng hạn như:

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport

Báo cáo thu được sẽ được tạo dựa trên dữ liệu sự kiện Google Analytics được thu thập trong 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 Data API, bạn không cần phải thao tác trên đườ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. Xem Hướng dẫn bắt đầu nhanh để biết các ví dụ về cách sử dụng thư viện ứng dụng.

Yêu cầu báo cáo tổng hợp

Để tạo yêu cầu bằng bảng tổng hợp, hãy sử dụng phương thức runPivotReport hoặc phương thức batchRunPivotReports.

Để yêu cầu dữ liệu được tổng hợp, bạn có thể tạo đối tượng RunPivotReportRequest. Bạn nên bắt đầu với các tham số yêu cầu sau:

• Mục nhập hợp lệ trong trường dateRanges.
• Ít nhất một mục nhập hợp lệ trong trường phương diện.
• Ít nhất một mục nhập hợp lệ trong trường metrics.
• Ít nhất hai mục tổng hợp hợp lệ trong trường thông tin tổng hợp.

Dưới đây là một yêu cầu mẫu có các trường đề xuất:

HTTP

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
  {
    "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
    "dimensions": [
        { "name": "browser" },
        { "name": "country" },
        { "name": "language" }
      ],
    "metrics": [{ "name": "sessions" }],
    "pivots": [
      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5
      },
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250
      },
      {
        "fieldNames": [
          "language"
        ],
        "limit": 15
      }
    ]
  }

Tổng hợp

Sử dụng các đối tượng Pivot (Tổng hợp) trong trường pivot của nội dung yêu cầu để xác định các tổng hợp báo cáo. Mỗi Pivot mô tả các hàng và cột phương diện hiển thị trong nội dung phản hồi báo cáo.

Data API v1 hỗ trợ nhiều bảng tổng hợp,miễn là tích của tham số giới hạn cho mỗi bảng tổng hợp không vượt quá 100.000.

Dưới đây là đoạn mã minh hoạ cách sử dụng pivots để tạo báo cáo về số phiên theo quốc gia, được chuyển hướng theo phương diện browser. Lưu ý cách truy vấn sử dụng trường orderBys để sắp xếp, cũng như các trường limit và offset để triển khai tính năng phân trang.

    "pivots": [
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250,
        "orderBys": [
          {
            "dimension": {
              "dimensionName": "country"
            }
          }
        ]
      },
      {
        "fieldNames": [
          "browser"
        ],
        "offset": 3,
        "limit": 3,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      }
    ],
    ...

Kích thước

Phương diện mô tả và nhóm dữ liệu sự kiện cho trang web hoặc ứng dụng của bạn. Ví dụ: phương diện city cho biết thành phố ("Paris" hoặc "New York") mà mỗi sự kiện bắt nguồn. Trong yêu cầu báo cáo, bạn có thể chỉ định số không hoặc nhiều phương diện.

Bạn phải xác định phương diện bên trong trường phương diện của nội dung yêu cầu. Để hiển thị trong báo cáo, các phương diện đó cũng phải được liệt kê trong trường fieldNames của đối tượng Pivot. Một phương diện sẽ không hiển thị trong báo cáo nếu không được dùng trong bất kỳ trung tâm nào của truy vấn tổng hợp. Không phải phương diện nào cũng phải có trong fieldNames của bảng tổng hợp. Bạn chỉ có thể sử dụng phương diện trong bộ lọc, chứ không phải trong fieldNames của bất kỳ bảng tổng hợp nào.

Dưới đây là đoạn mã minh hoạ cách sử dụng các trường dimension và fieldNames cho một bảng có các bảng tổng hợp browser, country và language:

    "pivots": [
      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      },
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250,
        "orderBys": [
          {
            "dimension": {
              "dimensionName": "country"
            }
          }
        ]
      },
      {
        "fieldNames": [
          "language"
        ],
        "limit": 10
      }
    ],

Chỉ số

Chỉ số là các phép đo định lượng dữ liệu sự kiện cho trang web hoặc ứng dụng của bạn. Trong yêu cầu báo cáo, bạn có thể chỉ định một hoặc nhiều chỉ số. Hãy xem phần Chỉ số API để biết danh sách đầy đủ các tên Chỉ số API có sẵn để chỉ định trong các yêu cầu.

Trong các yêu cầu báo cáo tổng hợp, các chỉ số được xác định bằng trường metrics của nội dung yêu cầu, tương tự như các phương thức Báo cáo chính.

Ví dụ bên dưới chỉ định số phiên sẽ được sử dụng làm giá trị chỉ số trong báo cáo:

    "metrics": [
      {
        "name": "sessions"
      }
    ],

Tổng hợp các chỉ số

Sử dụng trường metricAggregations của đối tượng Tổng hợp để tính toán các giá trị chỉ số tổng hợp cho mỗi bảng tổng hợp.

Hệ thống sẽ chỉ tính toán dữ liệu tổng hợp nếu trường metricAggregations được chỉ định trong một yêu cầu.

Dưới đây là đoạn mã của truy vấn yêu cầu tổng số cho thứ nguyên tổng hợp browser:

"pivots": [
  {
    "fieldNames": [
      "browser"
    ],
    "limit": 10,
    "metricAggregations": [
      "TOTAL",
    ]
  },
  ...

Các chỉ số đã tính được trả về trong trường aggregate (tổng hợp) của đối tượng RunPivotReportResponse. Đối với các hàng chỉ số tổng hợp, trường dimensionValues chứa giá trị đặc biệt là RESERVED_TOTAL, RESERVED_MAX hoặc RESERVED_MIN.

  "aggregates": [
    {
      "dimensionValues": [
        {
          "value": "Chrome"
        },
        {
          "value": "RESERVED_TOTAL"
        },
        {
          "value": "RESERVED_TOTAL"
        }
      ],
      "metricValues": [
        {
          "value": "4"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Firefox"
        },
        {
          "value": "RESERVED_TOTAL"
        },
        {
          "value": "RESERVED_TOTAL"
        }
      ],
      "metricValues": [
        {
          "value": "6"
        }
      ]
    },
  ....

  }

Phân trang

Tương tự như phương thức Báo cáo chính, yêu cầu tổng hợp cho phép bạn chỉ định các trường giới hạn và bồi thường trong đối tượng Pivot để triển khai tính năng phân trang. Chế độ cài đặt phân trang được áp dụng riêng cho từng bảng tổng hợp. Trường limit là bắt buộc cho mọi đối tượng Pivot để giới hạn số lượng giá trị riêng biệt của báo cáo.

Data API v1 hỗ trợ nhiều bảng tổng hợp miễn là tích của tham số limit cho mỗi bảng tổng hợp không vượt quá 100.000.

Dưới đây là đoạn mã minh hoạ cách sử dụng các trường offset và limit để truy xuất 5 kích thước language tiếp theo với độ lệch là 10:

      {
        "fieldNames": [
          "language"
        ],
        "offset": 10,
        "limit": 5
      }

Lọc

Tương tự như chức năng Báo cáo chính, bạn phải sử dụng bộ lọc phương diện trong phạm vi yêu cầu nếu muốn lọc phương diện trong yêu cầu báo cáo tổng hợp.

Sắp xếp

Bạn có thể kiểm soát hành vi sắp xếp của các truy vấn báo cáo tổng hợp cho từng bảng tổng hợp bằng cách sử dụng trường orderBys của đối tượng Pivot (Trục), trong đó có chứa danh sách các đối tượng OrderBy.

Mỗi OrderBy có thể chứa một trong các nội dung sau:

• DimensionOrderBy, sắp xếp kết quả theo giá trị của một phương diện.
• MetricOrderBy sẽ sắp xếp kết quả theo giá trị của một chỉ số.
• PivotOrderBy, dùng trong truy vấn tổng hợp và sắp xếp kết quả theo giá trị của một chỉ số trong một nhóm cột tổng hợp.

Ví dụ này cho thấy một đoạn mã cho định nghĩa tổng hợp làm xoay vòng báo cáo trên phương diện browser, sắp xếp kết quả theo chỉ số sessions theo thứ tự giảm dần.

      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      }

Phản hồi báo cáo

Phản hồi báo cáo tổng hợp của yêu cầu API báo cáo tổng hợp chủ yếu là một tiêu đề và các hàng.

Tiêu đề phản hồi

Tiêu đề báo cáo tổng hợp bao gồm PivotHeaders, DimensionHeaders và MetricHeaders. Các cột này liệt kê các cột trong báo cáo tổng hợp.

Ví dụ: báo cáo có thứ nguyên tổng hợp browser, country và language và chỉ số sessions sẽ tạo ra các tiêu đề như sau:

{
  "pivotHeaders": [
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "Chrome"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Firefox"
            }
          ]
        },
        ...

      ],
      ...
    },
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "United States"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Canada"
            }
          ]
        },
        ...

      ],
      ...
    },
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "English"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "French"
            }
          ]
        },
        ...

      ],
      ...
    }
  ],
  "dimensionHeaders": [
    {
      "name": "browser"
    },
    {
      "name": "country"
    },
    {
      "name": "language"
    }
  ],
  "metricHeaders": [
    {
      "name": "sessions",
      "type": "TYPE_INTEGER"
    }
  ],
  ...

}

Biểu đồ bên dưới minh hoạ vai trò của từng thành phần của Phản hồi báo cáo tổng hợp trong việc hiển thị báo cáo tổng hợp:

Hàng phản hồi

Phản hồi báo cáo tổng hợp của phương thức runPivotReport và batchRunPivotReports khác với phản hồi cho các phương thức Báo cáo chính như runReport và batchRunReports trong đó mỗi hàng phản hồi của báo cáo tổng hợp đại diện cho một ô của bảng, trong khi trong báo cáo thông thường, chỉ có một hàng phản hồi biểu thị một dòng bảng hoàn chỉnh.

Dưới đây là một mảnh của phản hồi trong báo cáo tổng hợp cho một truy vấn có các phương diện tổng hợp browser, country và language cũng như chỉ số sessions. Mỗi ô của báo cáo tổng hợp được trả về riêng lẻ:

  "rows": [
    {
      "dimensionValues": [
        {
          "value": "Chrome"
        },
        {
          "value": "United States"
        },
        {
          "value": "English"
        }
      ],
      "metricValues": [
        {
          "value": "1"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Firefox"
        },
        {
          "value": "Canada"
        },
        {
          "value": "French"
        }
      ],
      "metricValues": [
        {
          "value": "3"
        }
      ]
    },
    ...

  ]

Dữ liệu này tương ứng với hai ô được đánh dấu trong bảng dưới đây:

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 tổng hợp để tạo báo cáo về số phiên theo quốc gia, được chuyển hướng theo phương diện trình duyệt.

google-analytics-data/run_pivot_report.py

Mở trong Cloud Shell Xem trên GitHub

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
    DateRange,
    Dimension,
    Metric,
    OrderBy,
    Pivot,
    RunPivotReportRequest,
)


def run_sample():
    """Runs the sample."""
    # TODO(developer): Replace this variable with your Google Analytics 4
    #  property ID before running the sample.
    property_id = "YOUR-GA4-PROPERTY-ID"
    run_pivot_report(property_id)


def run_pivot_report(property_id="YOUR-GA4-PROPERTY-ID"):
    """Runs a pivot query to build a report of session counts by country,
    pivoted by the browser dimension."""
    client = BetaAnalyticsDataClient()

    request = RunPivotReportRequest(
        property=f"properties/{property_id}",
        date_ranges=[DateRange(start_date="2021-01-01", end_date="2021-01-30")],
        pivots=[
            Pivot(
                field_names=["country"],
                limit=250,
                order_bys=[
                    OrderBy(
                        dimension=OrderBy.DimensionOrderBy(dimension_name="country")
                    )
                ],
            ),
            Pivot(
                field_names=["browser"],
                offset=3,
                limit=3,
                order_bys=[
                    OrderBy(
                        metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True
                    )
                ],
            ),
        ],
        metrics=[Metric(name="sessions")],
        dimensions=[Dimension(name="country"), Dimension(name="browser")],
    )
    response = client.run_pivot_report(request)
    print_run_pivot_report_response(response)


def print_run_pivot_report_response(response):
    """Prints results of a runPivotReport call."""
    print("Report result:")
    for row in response.rows:
        for dimension_value in row.dimension_values:
            print(dimension_value.value)

        for metric_value in row.metric_values:
            print(metric_value.value)

run_pivot_report.py

Ứng dụng minh hoạ

Hãy xem ứng dụng minh hoạ báo cáo tổng hợp API phiên bản 1 của Google Analytics để biết ví dụ về cách tạo và hiển thị báo cáo tổng hợp bằng JavaScript.