Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

概要

Google Analytics Data API v1 を使用すると、ピボットテーブルを生成できます。ピボットテーブルは、1 つ以上のディメンションでデータをピボット（回転）してテーブル内の情報を再配置することで、データを可視化するデータ要約ツールです。

例として、次の元データテーブルを検討してください。

元データテーブル

このデータを使用して、ピボットテーブルを作成できます。このテーブルでは、セッションデータをブラウザ別に分類し、国と言語のディメンションを追加のピボットとして選択します。

ピボットされたデータテーブル

コアレポートと共通の機能

ピボットレポートリクエストは、多くの共有機能でコアレポートリクエストと同じセマンティクスを持ちます。たとえば、ページ分け、ディメンションフィルタ、ユーザープロパティは、ピボットレポートでもコアレポートと同じように動作します。このガイドでは、ピボットレポート機能を中心に説明します。Data API v1 のコアレポート機能に慣れるには、レポートの基本ガイドと高度なユースケースのガイドをご覧ください。

ピボットレポート方法

Data API v1 は、次のレポートメソッドでピボット機能をサポートしています。

runPivotReport: このメソッドは、Google アナリティクスのイベントデータのカスタマイズされたピボットレポートを返します。各ピボットは、レポートレスポンスに表示されるディメンションの列と行を表します。
batchRunPivotReports: runPivotReport メソッドのバッチバージョンです。1 回の API 呼び出しで複数のレポートを生成できます。

レポートエンティティを選択する

Data API v1 のすべてのメソッドでは、URL リクエストパス内で properties/GA_PROPERTY_ID の形式で Google アナリティクスのプロパティ ID を指定する必要があります。次に例を示します。

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

生成されるレポートは、指定した Google アナリティクスのプロパティで収集された Google アナリティクスイベントデータに基づいています。

Data API クライアントライブラリのいずれかを使用している場合は、リクエスト URL パスを手動で操作する必要はありません。ほとんどの API クライアントでは、文字列が properties/GA_PROPERTY_ID の形式の property パラメータが提供されています。クライアントライブラリの使用例については、クイックスタートガイドをご覧ください。

ピボットレポートのリクエスト

ピボットテーブルを含むリクエストを作成するには、runPivotReport メソッドまたは batchRunPivotReports メソッドを使用します。

ピボットデータをリクエストするには、RunPivotReportRequest オブジェクトを作成します。まずは、次のリクエストパラメータから始めることをおすすめします。

dateRanges フィールドの有効なエントリ。
dimensions フィールドに少なくとも 1 つの有効なエントリ。
metrics フィールドの 1 つ以上の有効なエントリ。
pivots フィールドに少なくとも 2 つの有効なピボットエントリがある。

推奨フィールドを含むリクエストの例を次に示します。

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 v1 では、各ピボットの limit パラメータの積が 100,000 を超えない限り、複数のピボットがサポートされます。

次のスニペットは、pivots を使用して、browser ディメンションでピボットされた国別のセッション数のレポートを作成する方法を示しています。クエリで並べ替えに orderBys フィールドを使用し、ページネーションの実装に limit フィールドと offset フィールドを使用していることに注目してください。

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

サイズ

ディメンションは、ウェブサイトまたはアプリのイベントデータを記述してグループ化します。たとえば、city ディメンションは、各イベントが発生した市区町村（「横浜」や「川崎」など）を示します。レポートリクエストでは、0 個以上のディメンションを指定できます。

ディメンションは、リクエスト本文の dimensions フィールド内で定義する必要があります。レポートに表示するには、これらのディメンションを Pivot オブジェクトの fieldNames フィールドにも指定する必要があります。ピボットクエリのピボットで使用されていないディメンションは、レポートに表示されません。すべてのディメンションがピボットの fieldNames に存在する必要はありません。ディメンションはフィルタでのみ使用でき、ピボットの fieldNames では使用できません。

次のスニペットは、browser、country、language ピボットを含むテーブルでの dimension フィールドと fieldNames フィールドの使用方法を示しています。

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

指標

指標は、ウェブサイトまたはアプリのイベントデータの定量的な測定値です。レポートリクエストでは、1 つ以上の指標を指定できます。リクエストで指定できる API 指標名の完全なリストについては、API 指標をご覧ください。

ピボットレポートリクエストでは、Core Reporting メソッドと同様に、リクエスト本文の metrics フィールドを使用して指標が定義されます。

次の例では、レポートで指標値として使用するセッション数を指定しています。

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

指標の集計

Pivot オブジェクトの metricAggregations フィールドを使用して、ピボットごとに集計された指標値を計算します。

集計は、リクエストで metricAggregations フィールドが指定されている場合にのみ計算されます。

次の例は、browser ピボットディメンションの合計をリクエストするクエリのスニペットです。

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

計算指標は、RunPivotReportResponse オブジェクトの aggregates フィールドに返されます。集計された指標行の場合、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"
        }
      ]
    },
  ....

  }

ページネーション

Core Reporting メソッドと同様に、ピボットリクエストでは、Pivot オブジェクトの limit フィールドと offset フィールドを指定して、ページ分けを実装できます。ページネーションの設定は、各ピボットに個別に適用されます。レポートのカーディナリティを制限するには、すべての Pivot オブジェクトに limit フィールドが必要です。

Data API v1 では、各ピボットの limit パラメータの積が 100,000 を超えない限り、複数のピボットがサポートされます。

次のスニペットは、offset フィールドと limit フィールドを使用して、オフセット 10 で次の 5 つの language ディメンションを取得する方法を示しています。

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

フィルタリング

コアレポート機能と同様に、ピボットレポートリクエストでディメンションをフィルタする場合は、リクエストスコープのディメンションフィルタを使用する必要があります。

並べ替え

ピボットレポートクエリの並べ替え動作は、OrderBy オブジェクトのリストを含む Pivot オブジェクトの orderBys フィールドを使用して、ピボットごとに個別に制御できます。

各 OrderBy には、次のいずれかを含めることができます。

DimensionOrderBy: ディメンションの値で結果を並べ替えます。
MetricOrderBy: 指標の値で結果を並べ替えます。
PivotOrderBy。ピボットクエリで使用され、ピボット列グループ内の指標の値で結果を並べ替えます。

この例は、browser ディメンションでレポートをピボットし、sessions 指標の降順で結果を並べ替えるピボット定義のスニペットを示しています。

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

回答を報告

ピボットレポート 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 などのコアレポートメソッドのレスポンスとは異なります。ピボットレポートレスポンスの各行はテーブルの 1 つのセルを表しますが、通常のレポートでは 1 つのレスポンス行がテーブルの 1 行全体を表します。

次の例は、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"
        }
      ]
    },
    ...

  ]

このデータは、次の表でハイライト表示されている 2 つのセルに対応しています。

元データテーブル

クライアントライブラリ

クライアントライブラリのインストール方法と構成方法については、クイックスタートガイドをご覧ください。

次の例では、クライアントライブラリを使用してピボットクエリを実行し、国別のセッション数のレポートを作成します。このレポートは、ブラウザディメンションでピボットされます。

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 = 'YOUR-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: '2021-01-01',
          endDate: '2021-01-30',
        },
      ],
      pivots: [
        {
          fieldNames: ['country'],
          limit: 250,
          orderBys: [
            {
              dimension: {
                dimensionName: 'country',
              },
            },
          ],
        },
        {
          fieldNames: ['browser'],
          offset: 3,
          limit: 3,
          orderBys: [
            {
              metric: {
                metricName: 'sessions',
              },
              desc: true,
            },
          ],
        },
      ],
      metrics: [
        {
          name: 'sessions',
        },
      ],
      dimensions: [
        {
          name: 'country',
        },
        {
          name: 'browser',
        },
      ],
    });
    printPivotReportResponse(response);
  }

  runPivotReport();

  // Prints results of a runReport call.
  function printPivotReportResponse(response) {
    console.log('Report 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

デモアプリケーション

JavaScript を使用してピボットレポートを作成して表示する方法の例については、Google アナリティクス API v1 ピボットレポートのデモアプリケーションをご覧ください。

概要 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

コアレポートと共通の機能

ピボット レポート方法

レポート エンティティを選択する

ピボット レポートのリクエスト

HTTP

ピボット

サイズ

指標

指標の集計

ページネーション

フィルタリング

並べ替え

回答を報告

レスポンス ヘッダー

レスポンスの行

クライアント ライブラリ

PHP

Python

Node.js

デモ アプリケーション

概要

ピボットレポート方法

レポートエンティティを選択する

ピボットレポートのリクエスト

レスポンスヘッダー

クライアントライブラリ

デモアプリケーション