本頁面由 Cloud Translation API 翻譯而成。

總覽

您可以使用 Google Analytics Data API 第 1 版產生資料透視表。資料透視資料表是一種資料摘要工具，可藉由重新調整對一或多個資料透視 (旋轉) 資料，藉此凸顯表格中的資訊維度。

舉例來說，請考量下列原始資料表：

原始資料表

您可以根據這些資料建立資料透視表，進一步細分按瀏覽器劃分的工作階段資料，並選取國家/地區和語言維度做為其他資料透視

資料透視表

與核心報表共用的功能

資料透視報表要求與核心報表要求中的語意相同有許多共同功能例如分頁、維度篩選器和使用者資源在資料透視報表中的運作方式與核心報表相同。這個本指南著重於透視報表功能熟悉核心肌群《Data API v1》的報表功能：請參閱報表基本概念指南。以及進階用途指南

資料透視報表方法

Data API 第 1 版支援下列報表方式中的資料透視功能：

runPivotReport 這個方法傳回 Google Analytics 事件資料的自訂資料透視報表。每項資料透視表中說明瞭報表回應中會顯示的維度欄和列。
batchRunPivotReports 是 runPivotReport 方法的批次版本，使用單一 API 呼叫產生多份報表。

選取檢舉實體

所有 Data API 第 1 版的方法都需要 Google Analytics 資源 ID 會在網址要求路徑中指定，格式為 properties/GA_PROPERTY_ID，例如：

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

系統會根據 Google Analytics 事件資料產生最終報表收集到的資訊

如果您使用其中一個 Data API 用戶端程式庫，則無需手動操作要求網址路徑大部分的 API 用戶端提供的 property 參數預期字串為 properties/GA_PROPERTY_ID。請參閱快速入門指南，瞭解使用用戶端程式庫的範例。

樞紐分析報告要求

如要使用資料透視表建構要求，請使用 runPivotReport 或 batchRunPivotReports 方法。

如要索取已透視的資料，可以建立 RunPivotReportRequest 物件。建議您先從以下要求參數著手：

dateRanges 欄位中的有效項目。
在「dimensions」欄位中至少一個有效項目。
在「metrics」欄位中至少有一個有效項目。
透視欄位中至少兩個有效的資料透視項目。

以下是包含建議欄位的要求範例：

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

資料透視

在要求的 pivot 欄位中使用 Pivot 物件定義報表資料透視選項每個 Pivot 都描述了可見維度欄和列。

只要限制產品的乘積，Data API 第 1 版就能支援多個資料透視參數的大小不得超過 100,000。

以下程式碼片段示範如何使用 pivots 建立以下報表：按國家/地區劃分的工作階段數，並按「browser」維度透視。請注意查詢的 orderBys 欄位排序，以及限制和 offset 欄位來實作分頁。

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

尺寸

維度：描述事件性並分組網站或應用程式舉例來說，city 維度會指出城市 (「巴黎」) 或「紐約」)。在報表請求中，您可以：請指定零個或多個維度

維度必須在維度欄位值。這些維度必須也顯示在報表中列於 fieldNames Pivot 物件的欄位。報表中不會顯示未使用任何維度的維度做為資料透視表查詢依據。並非所有維度都必須出現在資料透視表中 fieldNames。維度只能用在篩選器中，無法用於任何資料透視的 fieldNames。

以下程式碼片段示範如何使用 dimension 和 fieldNames 欄位針對含有 browser、country 和 language 資料透視的資料表：

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

指標

指標是針對下列項目的量化評估資料：網站或應用程式在報表要求中，您可以指定一或多個指標。如需 API 指標名稱的完整清單，請參閱 API 指標。都能在請求中指定

在樞紐分析報告要求中，指標是使用 metrics 欄位的請求主體，與核心報表方法類似。

以下範例將指定工作階段計數做為指標值報告：

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

指標匯總

使用 metricAggregations 模式欄位，以便計算匯總指標。每個資料透視表的值

只有在產生 metricAggregations 時，系統才會計算匯總資料 ] 欄位並未在要求中指定。

以下查詢程式碼片段會要求 browser 資料透視維度：

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

計算指標會傳回匯總 RunPivotReportResponse 中的欄位物件。如果是匯總指標資料列，dimensionValues 欄位包含 RESERVED_TOTAL、RESERVED_MAX 或 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"
        }
      ]
    },
  ....

  }

分頁

與核心報表方法類似，資料透視要求可讓您可指定限制和 offset 欄位 Pivot 物件，用於實作分頁。分頁設定會套用至每個資料透視表。每個 Pivot 物件都必須有 limit 欄位，才能限制報表基數

只要 limit 的乘積，Data API 第 1 版就能支援多個資料透視參數的大小不得超過 100,000。

以下程式碼片段示範如何使用 offset 和 limit 欄位擷取偏移值為 10 的接下來五個 language 維度：

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

篩選

與核心報表功能類似，要求限定範圍的維度篩選器如果需要在資料透視報表中使用維度篩選功能，則必須使用這個屬性請求。

排序

每個資料透視表都可以控制樞紐分析報告查詢的排序個別使用 orderBys 是 Pivot 物件的欄位，其中包含 OrderBy 物件。

每個 OrderBy 都可以包含下列其中一個項目：

DimensionOrderBy, 按維度值排序結果。
MetricOrderBy，排序按照指標值產生結果
PivotOrderBy，用於透視查詢，並按指標值排序結果套用了資料透視表資料欄群組中的內容

這個範例是透視報表透視型資料透視定義的程式碼片段「browser」維度，按 sessions 指標排序結果，遞減排序。

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

檢舉回應

資料透視表的 Pivot 報告回應報表 API 請求主要為標頭和列。

回應標頭

樞紐分析表報告標題由 PivotHeaders 組成， DimensionHeaders 和 MetricHeaders，列出。

舉例來說，如果報表含有 browser、country 和 language 資料透視維度 sessions 指標會產生類似下方的標頭：

{
  "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"
    }
  ],
  ...

}

下方圖表說明資料透視報表各部分的作用轉譯樞紐分析報告的回應：

原始資料表

回應列

runPivotReport 的樞紐分析報告回應和 batchRunPivotReports 方法與核心報表方法的回應不同例如 runReport 和 batchRunReports 該每個樞紐分析報告回應列中的單一儲存格表格，而在一般報表中，單一回應列則代表完整的。

以下是樞紐分析報告回應片段：使用 browser、country 和 language 資料透視維度和 sessions指標。系統會分別傳回樞紐分析報告中的每個儲存格：

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

  ]

此資料對應下表中醒目顯示的兩個儲存格：

原始資料表

用戶端程式庫

請參閱快速入門指南中的如何安裝及設定用戶端程式庫。

以下範例使用用戶端程式庫執行資料透視查詢以建立按國家/地區劃分的工作階段計數報表，按瀏覽器維度透視。

PHP

google-analytics-data/src/run_pivot_report.php

在 Cloud Shell 中開啟前往 GitHub 查看

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()
        );
    }
}run_pivot_report.php

Python

google-analytics-data/run_pivot_report.py

在 Cloud Shell 中開啟前往 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

Node.js

google-analytics-data/run_pivot_report.js

在 Cloud Shell 中開啟前往 GitHub 查看

  // 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);
      });
    });
  }run_pivot_report.js

試用版應用程式

請參閱 Google Analytics API v1 樞紐分析表報告示範應用程式使用 JavaScript 建立及顯示樞紐分析報告的範例。