Tổng quan

Google Analytics Data API v1 cho phép bạn tạo bảng tổng hợp. Xoay vòng bảng 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 xoay vòng (xoay vòng) dữ liệu của bạn trên một hoặc nhiều thứ nguyên.

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

Bảng dữ liệu thô

Bằng cách sử dụng dữ liệu này, bạn có thể xây dựng một bảng tổng hợp, chia nhỏ dữ liệu phiên theo trình duyệt, trong đó phương diện quốc gia và ngôn ngữ được chọn là các trục khác.

Bảng dữ liệu tổng hợp

Các tính năng được chia sẻ với báo cáo cốt lõi

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 được chia sẻ. Ví dụ về tính năng phân trang, Bộ lọc phương diện và Người dùng Tài sản hoạt động giống nhau trong Báo cáo tổng hợp dưới dạng Báo cáo chính. Chiến dịch 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 Core Chức năng báo cáo 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 về 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 v1 hỗ trợ chức năng tổng hợp trong các phương thức báo cáo sau đây:

  • runPivotReport Phương pháp này sẽ trả về một báo cáo tổng hợp tuỳ chỉnh về dữ liệu sự kiện Google Analytics của bạn. Một Bảng tổng hợp 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à là phiên bản lô 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 giá trị nhận dạng tài sản Google Analytics được chỉ định bên trong đường dẫn yêu cầu URL dưới dạng properties/GA_PROPERTY_ID, chẳng hạn như:

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

Báo cáo kết quả 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 được chỉ định.

Nếu bạn đang sử dụng một trong các thư viện ứng dụng Data API, không cần thao tác đường dẫn URL yêu cầu theo cách thủ công. Hầu hết ứng dụng API cung cấp tham số property mong đợi một chuỗi ở dạng properties/GA_PROPERTY_ID Xem Hướng dẫn bắt đầu nhanh để xem 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 runPivotReport hoặc batchRunPivotReports .

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

  • Giá trị 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.
  • Có ít nhất một mục hợp lệ trong trường chiso (chỉ số).
  • Ít nhất hai mục nhập tổng hợp hợp lệ trong trường tổng hợp.

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

HTTP

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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
      }
    ]
  }

Xoay vòng

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

Data API v1 hỗ trợ nhiều bảng tổng hợp miễn là sản phẩm của giới hạn này 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 tổng hợp theo phương diện browser. Lưu ý cách sử dụng trường orderBys cho sắp xếp, giới hạn và Trường phần bù để 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") nơi bắt nguồn từng sự kiện. Trong yêu cầu báo cáo, bạn có thể chỉ định không hoặc nhiều phương diện.

Bạn phải xác định thứ nguyên bên trong 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 fieldNames của đối tượng Pivot. Một phương diện sẽ không xuất hiện trong một báo cáo nếu không được sử dụng trong bất kỳ bảng tổng hợp truy vấn. Không phải mọi phương diện đều phải hiển thị trong fieldNames. Bạn chỉ có thể sử dụng thứ nguyê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 dimensionfieldNames cho bảng có trụ browser, countrylanguage:

    "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 lường đị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 bài viết Chỉ số API để biết danh sách đầy đủ tên các chỉ số API có sẵn để chỉ định trong các yêu cầu.

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

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

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

Tổng hợp chỉ số

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

Các số liệu tổng hợp sẽ chỉ được tính nếu các metricAggregations được chỉ định trong yêu cầu.

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

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

Các chỉ số đã tính toán được trả về dưới dạng dữ liệu tổng hợp trường của RunPivotReportResponse . Đối với các hàng chỉ số tổng hợp, trường dimensionValues chứa giá trị đặc biệt của 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ư các phương pháp báo cáo chính, yêu cầu tổng hợp cho phép bạn để xác định giới hạnphần bù trong trường Đối tượng Tổng hợp để triển khai tính năng phân trang. Các 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à trường bắt buộc cho mọi đối tượng Pivot để giới hạn báo cáo lượng số.

Data API v1 hỗ trợ nhiều bảng tổng hợp, miễn là sản phẩm của 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 offsetlimit để truy xuất năm thứ nguyên 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ộ lọc phương diện trong phạm vi yêu cầu phải được sử dụng nếu muốn lọc phương diện trong báo cáo tổng hợp của bạn.

Sắp xếp

Có thể kiểm soát hành vi sắp xếp theo thứ tự của các truy vấn báo cáo tổng hợp cho mỗi bảng tổng hợp bằng cách sử dụng hàm orderBys trường của đối tượng Pivot, chứa danh sách Đố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ắp xếp kết quả theo giá trị của chỉ số.
  • PivotOrderBy, được sử dụng trong tổng hợp truy vấn và sắp xếp kết quả theo giá trị của một chỉ số trong nhóm cột tổng hợp.

Ví dụ này hiển thị một đoạn mã cho định nghĩa bảng tổng hợp xoay quanh báo cáo 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 trong báo cáo tổng hợp của một bảng tổng hợp yêu cầu API báo cáo chủ yếu là 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, DimensionHeadersMetricHeaders các cột trong báo cáo tổng hợp.

Ví dụ: báo cáo có các phương diện tổng hợp browser, countrylanguage và chỉ số sessions sẽ tạo ra 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 Báo cáo tổng hợp Phản hồi khi hiển thị báo cáo tổng hợp:

Bảng dữ liệu thô

Hàng phản hồi

Phản hồi cho báo cáo tổng hợp của runPivotReportbatchRunPivotReports khác với phản hồi cho các phương thức Báo cáo chính như runReportbatchRunReports 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 ô duy nhất của , trong khi trong báo cáo thông thường, một hàng phản hồi đơn lẻ thể hiện đầy đủ dòng trong bảng.

Dưới đây là phân đoạn của phản hồi trong báo cáo tổng hợp cho một với các phương diện tổng hợp browser, countrylanguage cùng với phương diện 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 làm nổi bật trong bảng bên dưới:

Bảng dữ liệu thô

Thư viện ứng dụng

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.

Các ví dụ sau đây sử dụng thư viện ứng dụng để chạy một truy vấn tổng hợp nhằm tạo một báo cáo về số phiên theo quốc gia, được tổng hợp theo phương diện trình duyệt.

PHP

use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient;
use Google\Analytics\Data\V1beta\DateRange;
use Google\Analytics\Data\V1beta\Dimension;
use Google\Analytics\Data\V1beta\Metric;
use Google\Analytics\Data\V1beta\OrderBy;
use Google\Analytics\Data\V1beta\OrderBy\DimensionOrderBy;
use Google\Analytics\Data\V1beta\OrderBy\MetricOrderBy;
use Google\Analytics\Data\V1beta\Pivot;
use Google\Analytics\Data\V1beta\RunPivotReportRequest;
use Google\Analytics\Data\V1beta\RunPivotReportResponse;

/**
 * Runs a pivot query to build a report of session counts by country,
 * pivoted by the browser dimension.
 * @param string $propertyId Your GA-4 Property ID
 */
function run_pivot_report(string $propertyId)
{
    // Create an instance of the Google Analytics Data API client library.
    $client = new BetaAnalyticsDataClient();

    // Make an API call.
    $request = (new RunPivotReportRequest())
        ->setProperty('properties/' . $propertyId)
        ->setDateRanges([new DateRange([
            'start_date' => '2021-01-01',
            'end_date' => '2021-01-30',
            ]),
        ])
        ->setPivots([
            new Pivot([
                'field_names' => ['country'],
                'limit' => 250,
                'order_bys' => [new OrderBy([
                    'dimension' => new DimensionOrderBy([
                        'dimension_name' => 'country',
                    ]),
                ])],
            ]),
            new Pivot([
                'field_names' => ['browser'],
                'offset' => 3,
                'limit' => 3,
                'order_bys' => [new OrderBy([
                    'metric' => new MetricOrderBy([
                        'metric_name' => 'sessions',
                    ]),
                    'desc' => true,
                ])],
            ]),
        ])
        ->setMetrics([new Metric(['name' => 'sessions'])])
        ->setDimensions([
            new Dimension(['name' => 'country']),
            new Dimension(['name' => 'browser']),
        ]);
    $response = $client->runPivotReport($request);

    printPivotReportResponse($response);
}

/**
 * Print results of a runPivotReport call.
 * @param RunPivotReportResponse $response
 */
function printPivotReportResponse(RunPivotReportResponse $response)
{
    print 'Report result: ' . PHP_EOL;

    foreach ($response->getRows() as $row) {
        printf(
            '%s %s' . PHP_EOL,
            $row->getDimensionValues()[0]->getValue(),
            $row->getMetricValues()[0]->getValue()
        );
    }
}

Python

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)


Node.js

  // TODO(developer): Uncomment this variable and replace with your
  // Google Analytics 4 property ID before running the sample.
  // propertyId = Y'OUR-GA4-PROPERTY-ID;'

  // Imports the Google Analytics Data API client library.
  const {BetaAnalyticsDataClient} = require(@'google-analytics/data)';

  // Initialize client that will be used to send requests. This client only
  // needs to be created once, and can be reused for multiple requests.
  const analyticsDataClient = new BetaAnalyticsDataClient();

  // Runs a pivot query to build a report of session counts by country, pivoted by the browser dimension.
  async function runPivotReport() {
    const [response] = await analyticsDataClient.runPivotReport({
      property: `properties/${propertyId}`,
      dateRanges: [
        {
          startDate: 2'021-01-01,'
          endDate: 2'021-01-30,'
        },
      ],
      pivots: [
        {
          fieldNames: [c'ountry]',
          limit: 250,
          orderBys: [
            {
              dimension: {
                dimensionName: c'ountry,'
              },
            },
          ],
        },
        {
          fieldNames: [b'rowser]',
          offset: 3,
          limit: 3,
          orderBys: [
            {
              metric: {
                metricName: s'essions,'
              },
              desc: true,
            },
          ],
        },
      ],
      metrics: [
        {
          name: s'essions,'
        },
      ],
      dimensions: [
        {
          name: c'ountry,'
        },
        {
          name: b'rowser,'
        },
      ],
    });
    printPivotReportResponse(response);
  }

  runPivotReport();

  // Prints results of a runReport call.
  function printPivotReportResponse(response) {
    console.log(R'eport result:)';
    response.rows.forEach(row = >{
      row.dimensionValues.forEach(dimensionValue = >{
        console.log(dimensionValue.value);
      });

      row.metricValues.forEach(metricValue = >{
        console.log(metricValue.value);
      });
    });
  }r

Ứng dụng minh hoạ

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