このページは Cloud Translation API によって翻訳されました。

概要

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

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

元データのテーブル

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

ピボットデータ表

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

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

ピボットレポート方法

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

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

報告エンティティの選択

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

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

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

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

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

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

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

dateRanges フィールドの有効なエントリ。
ディメンションフィールドに有効なエントリが 1 つ以上ある。
metrics フィールドの 1 つ以上の有効なエントリ。
ピボットフィールドに有効なピボットエントリを 2 つ以上指定してください。

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

HTTP

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_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 メソッドと同様に、ピボットリクエストでは、ピボットオブジェクトの limit フィールドと offset フィールドを指定して、ページ分割を実装できます。ページ分けの設定は、各ピボットに個別に適用されます。レポートの基数を制限するには、すべての Pivot オブジェクトに limit フィールドが必要です。

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

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

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

フィルタリング

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

並べ替え

ピボットレポートクエリの順序動作は、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 などの Core Reporting メソッドのレスポンスと異なります。各ピボットレポートレスポンス行はテーブルの 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 つのセルに対応しています。

元データのテーブル

クライアントライブラリ

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

次の例では、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

デモアプリケーション

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

概要

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

ピボット レポート方法

報告エンティティの選択

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

HTTP

ピボット

ディメンション

指標

指標の集計

ページネーション

フィルタリング

並べ替え

回答を報告

レスポンス ヘッダー

レスポンス行

クライアント ライブラリ

デモ アプリケーション

ピボットレポート方法

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

レスポンスヘッダー

クライアントライブラリ

デモアプリケーション