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

概要

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

たとえば、次の元データテーブルについて考えてみましょう。

元データテーブル

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

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

コアレポートと共有される機能

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

ピボットレポートの方法

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

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

報告エンティティを選択する

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

  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 を超えない限り、複数のピボットをサポートします。

次のスニペットは、browser ディメンションでピボットされた国別のセッション数のレポートを作成するために pivots を使用する方法を示しています。クエリで 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 指標をご覧ください。

ピボットレポートのリクエストでは、コアレポーティングメソッドと同様に、リクエスト本文の 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"
        }
      ]
    },
  ....

  }

ページネーション

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

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

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

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

フィルタリング

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

並べ替え

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

すべての 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

デモ アプリケーション

概要

ピボットレポートの方法

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

レスポンスヘッダー

クライアントライブラリ

デモアプリケーション