概要

Google アナリティクス Data API v1 では、ピボット テーブルを生成できます。ピボット テーブルは、特徴のリストを再編成してデータを可視化するデータ要約ツールです。 テーブル内の情報をピボット(ローテーション)して、 定義できます。

例として、次の元データのテーブルについて考えてみます。

元データのテーブル

このデータを使用してピボット テーブルを作成し、 ブラウザ別のセッション数 データ(国と言語のディメンションが選択されている) ピボット化できます

ピボット データ テーブル

コアレポートと共有機能

ピボット レポートのリクエストは、 多くの共有機能があります。ページ分け、ディメンション フィルタ、ユーザーなど プロパティ。ピボット レポートでは、コアレポートと同じように動作します。この このガイドでは、ピボットレポート機能に絞って説明します。「Core Data API v1 のレポート機能については、レポートの基本ガイドをご覧ください。 高度なユースケースのガイドをご覧ください。

ピボット レポート方法

Data API v1 では、以下のレポート メソッドのピボット機能がサポートされています。

  • runPivotReport このメソッド は、Google アナリティクスのイベントデータのカスタマイズされたピボット レポートを返します。各 ピボットは、レポートのレスポンスに表示されるディメンションの列と行を表します。

  • batchRunPivotReports runPivotReport メソッドのバッチ バージョンです。これにより、 1 回の API 呼び出しで複数のレポートを作成できます

報告エンティティの選択

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

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

結果のレポートは 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 は、上限の積である限り、複数のピボットをサポートします。 各ピボットのパラメータが 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 ディメンションは都市(「パリ」)を示します。 (例: 「ニューヨーク」)。レポート リクエストでは、 0 個以上のディメンションを指定します。

ディメンションは ディメンション フィールド名.レポートにこれらのディメンションを表示するには、次の条件も満たしている必要があります。 fieldNames にリストされます。 Pivot オブジェクトのフィールドです。 使用されていないディメンションはレポートに表示されません ピボットクエリの ピボットフィールドが作成されますすべてのディメンションがピボットの fieldNames。ディメンションをフィルタでのみ使用でき、 ピボットの fieldNames

以下は、dimension フィールドと fieldNames フィールドの使用方法を示すスニペットです。 browsercountrylanguage のピボットを含むテーブルの場合:

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

指標の集計

metricAggregations を使用する 集計指標を計算するための Pivot オブジェクトのフィールドです。 各ピボットの値です

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

以下は、 browser ピボット ディメンション:

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

計算された指標は、集計値で返されます。 RunPivotReportResponse フィールド 渡されます。集計指標の行の場合、dimensionValues フィールド 特別な値 RESERVED_TOTALRESERVED_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 オブジェクトでページ分けを実装します。 ページ分けの設定は、各ピボットに個別に適用されます。 limit フィールドは、すべての Pivot オブジェクトで必須であり、 基づいています。

Data API v1 は、limit の積である限り、複数のピボットをサポートします。 各ピボットのパラメータが 100,000 を超えないようにしてください。

以下は、offset フィールドと limit フィールドを使用して以下を行うためのスニペットです。 オフセット 10 で次の 5 つの language ディメンションを取得します。

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

フィルタリング

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

並べ替え

ピボット レポートのクエリの順序付けは、ピボットごとに制御できる orderBys を使用して個別に フィールドの Pivot フィールドです。このフィールドには、 OrderBy オブジェクト。

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

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

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

回答を報告

ピボットのピボット レポートのレスポンス Reporting API リクエストは、主にヘッダーと行です。

レスポンス ヘッダー

ピボット レポートのヘッダーは、PivotHeadersDimensionHeaders および MetricHeaders です。これにより、 ピボットレポート

たとえば、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 メソッドによるレスポンスは、コアレポート メソッドのレスポンスと異なる runReport など と batchRunReports ピボット レポートの各回答行は、 ですが、通常のレポートでは 1 行がレスポンスの完了を表し、 使用します。

以下は、ピボットされたレポートのレスポンスの一部分です。 browsercountrylanguage のピボット ディメンションと、 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

<ph type="x-smartling-placeholder"></ph> google-analytics-data/src/run_pivot_report.php
<ph type="x-smartling-placeholder"></ph> 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()
        );
    }
}

Python

<ph type="x-smartling-placeholder"></ph> google-analytics-data/run_pivot_report.py
<ph type="x-smartling-placeholder"></ph> 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)


Node.js

<ph type="x-smartling-placeholder"></ph> google-analytics-data/run_pivot_report.js
<ph type="x-smartling-placeholder"></ph> 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);
      });
    });
  }r

デモ アプリケーション

Google Analytics API v1 のピボット レポートのデモを見る アプリケーション をご覧ください。