總覽

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

舉例來說,請考量下列原始資料表:

原始資料表

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

資料透視表

與核心報表共用的功能

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

資料透視報表方法

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

  • runPivotReport 這個方法 傳回 Google Analytics 事件資料的自訂資料透視報表。每項 資料透視表中說明瞭報表回應中會顯示的維度欄和列。

  • batchRunPivotReportsrunPivotReport 方法的批次版本, 使用單一 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。請參閱快速入門指南 ,瞭解使用用戶端程式庫的範例。

樞紐分析報告要求

如要使用資料透視表建構要求,請使用 runPivotReportbatchRunPivotReports 方法。

如要索取已透視的資料,可以建立 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

以下程式碼片段示範如何使用 dimensionfieldNames 欄位 針對含有 browsercountrylanguage 資料透視的資料表:

    "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_TOTALRESERVED_MAXRESERVED_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。

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

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

篩選

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

排序

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

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

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

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

檢舉回應

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

回應標頭

樞紐分析表報告標題由 PivotHeaders 組成, DimensionHeadersMetricHeaders,列出 。

舉例來說,如果報表含有 browsercountrylanguage 資料透視維度 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 方法與核心報表方法的回應不同 例如 runReportbatchRunReports每個樞紐分析報告回應列中的單一儲存格 表格,而在一般報表中,單一回應列則代表完整的 。

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

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

  ]

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

原始資料表

用戶端程式庫

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

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

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

試用版應用程式

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