ภาพรวม

Google Analytics Data API v1 ช่วยให้คุณสร้างตาราง Pivot ได้ ตาราง Pivot เป็นเครื่องมือสรุปข้อมูลที่แสดงข้อมูลเป็นภาพโดยการจัดเรียงข้อมูลใหม่ในตารางด้วยการหมุนข้อมูลในมิติข้อมูลอย่างน้อย 1 รายการ

ตัวอย่างเช่น ลองพิจารณาตารางข้อมูลดิบต่อไปนี้

ตารางข้อมูลดิบ

การใช้ข้อมูลนี้ทำให้สามารถสร้างตาราง Pivot ที่แบ่งข้อมูลเซสชันตามเบราว์เซอร์ โดยเลือกมิติข้อมูลประเทศและภาษาเป็น Pivot เพิ่มเติม

ตารางข้อมูลที่หมุน

ฟีเจอร์ที่แชร์กับรายงานหลัก

คำขอการรายงาน Pivot มีความหมายเหมือนกับคำขอรายงานหลักสำหรับฟีเจอร์ที่แชร์หลายรายการ ตัวอย่างเช่น การใส่เลขหน้า ตัวกรองมิติข้อมูล และพร็อพเพอร์ตี้ผู้ใช้จะทำงานเหมือนกันในรายงาน Pivot และรายงานหลัก คู่มือนี้จะเน้นที่ฟีเจอร์การรายงาน Pivot หากต้องการทำความคุ้นเคยกับฟังก์ชันการทำงานของการรายงานหลัก ของ Data API v1 โปรดอ่านคู่มือข้อมูลเบื้องต้นเกี่ยวกับการรายงาน รวมถึงคู่มือกรณีการใช้งานขั้นสูง

วิธีการรายงาน Pivot

Data API v1 รองรับฟังก์ชันการทำงาน Pivot ในวิธีการรายงานต่อไปนี้

  • runPivotReport วิธีนี้ จะแสดงผลรายงาน Pivot ที่กําหนดเองของข้อมูลเหตุการณ์ Google Analytics ของคุณ Pivot แต่ละรายการจะอธิบายคอลัมน์และแถวมิติข้อมูลที่มองเห็นได้ในการตอบกลับของรายงาน

  • batchRunPivotReports นี่คือเวอร์ชันแบบกลุ่มของเมธอด runPivotReport ซึ่งช่วยให้สร้างรายงานหลายรายการได้โดยใช้การเรียก API ครั้งเดียว

เลือกเอนทิตีการรายงาน

เมธอดทั้งหมดของ Data API v1 กำหนดให้ระบุ ตัวระบุพร็อพเพอร์ตี้ Google Analytics ภายใน เส้นทางคำขอ URL ในรูปแบบ properties/GA_PROPERTY_ID เช่น

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

ระบบจะสร้างรายงานที่ได้จากข้อมูลเหตุการณ์ Google Analytics ที่รวบรวมในพร็อพเพอร์ตี้ Google Analytics ที่ระบุ

หากคุณใช้ไลบรารีของไคลเอ็นต์ Data API รายการใดรายการหนึ่ง ก็ ไม่จำเป็นต้องจัดการเส้นทาง URL ของคำขอด้วยตนเอง ไคลเอ็นต์ API ส่วนใหญ่มีพารามิเตอร์ property ที่คาดหวังสตริงในรูปแบบ properties/GA_PROPERTY_ID ดูตัวอย่างการใช้ไลบรารีของไคลเอ็นต์ได้ในคู่มือเริ่มใช้งานฉบับย่อ

คำขอรายงาน Pivot

หากต้องการสร้างคำขอด้วยตาราง Pivot ให้ใช้เมธอด runPivotReport หรือ batchRunPivotReports

หากต้องการขอข้อมูลที่หมุนแล้ว คุณสามารถสร้างออบเจ็กต์ RunPivotReportRequest ได้ เราขอแนะนำให้เริ่มต้นด้วยพารามิเตอร์คำขอต่อไปนี้

  • รายการที่ถูกต้องในช่อง dateRanges
  • รายการที่ถูกต้องอย่างน้อย 1 รายการในช่อง dimensions
  • รายการที่ถูกต้องอย่างน้อย 1 รายการในช่อง metrics
  • รายการ Pivot ที่ถูกต้องอย่างน้อย 2 รายการในช่อง pivots

ตัวอย่างคำขอที่มีช่องที่แนะนำมีดังนี้

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 ของเนื้อหาคำขอ เพื่อกำหนด Pivot ของรายงาน Pivot แต่ละรายการจะอธิบายคอลัมน์และแถวมิติข้อมูลที่มองเห็นได้ในการตอบกลับของรายงาน

Data API v1 รองรับ Pivot หลายรายการตราบใดที่ผลคูณของพารามิเตอร์ limit สำหรับ Pivot แต่ละรายการไม่เกิน 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 ของเนื้อหาคำขอ มิติข้อมูลเหล่านั้นต้องแสดงอยู่ในช่อง fieldNames ของออบเจ็กต์ Pivot ด้วยจึงจะมองเห็นได้ในรายงาน มิติข้อมูลจะไม่ปรากฏในรายงานหากไม่ได้ใช้ใน Pivot ใดๆ ของคําค้นหา Pivot ไม่จำเป็นต้องระบุมิติข้อมูลทั้งหมดใน fieldNames ของ Pivot คุณสามารถใช้มิติข้อมูลในตัวกรองเท่านั้นและไม่ได้ใช้ใน fieldNames ของ Pivot ใดๆ

ข้อมูลโค้ดต่อไปนี้แสดงการใช้ช่อง dimension และ fieldNames สำหรับตารางที่มี Pivot browser, country และ language

    "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

ในคำขอรายงาน Pivot เมตริกจะกำหนดโดยใช้ช่อง metrics ของ เนื้อหาคำขอ ซึ่งคล้ายกับ เมธอดการรายงานหลัก

ตัวอย่างต่อไปนี้ระบุจำนวนเซสชันที่จะใช้เป็นค่าเมตริกในรายงาน

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

การรวมเมตริก

ใช้ช่อง metricAggregations ของออบเจ็กต์ Pivot เพื่อคำนวณค่าเมตริกที่รวม สำหรับ Pivot แต่ละรายการ

ระบบจะคำนวณการรวมก็ต่อเมื่อระบุช่อง metricAggregations ในคำขอ

ตัวอย่างต่อไปนี้เป็นข้อมูลโค้ดของคําค้นหาที่ขอผลรวมสําหรับมิติข้อมูล Pivot browser

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

ระบบจะแสดงผลเมตริกที่คำนวณแล้วในช่อง aggregates ของออบเจ็กต์ RunPivotReportResponse สำหรับแถวเมตริกที่รวม ช่อง 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 เพื่อใช้การใส่เลขหน้าได้ ซึ่งคล้ายกับเมธอด Core Reporting การตั้งค่าการใส่เลขหน้าจะมีผลกับ Pivot แต่ละรายการ ช่อง limit จำเป็นสำหรับออบเจ็กต์ Pivot ทุกรายการเพื่อจำกัดจำนวนคาร์ดินัลลิตีของรายงาน

Data API v1 รองรับ Pivot หลายรายการตราบใดที่ผลคูณของพารามิเตอร์ limit สำหรับ Pivot แต่ละรายการไม่เกิน 100,000

ข้อมูลโค้ดต่อไปนี้แสดงการใช้ช่อง offset และ limit เพื่อดึงมิติข้อมูล language 5 รายการถัดไปโดยมีออฟเซ็ตเป็น 10

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

การกรอง

ตัวกรองมิติข้อมูลที่กำหนดขอบเขตระดับคำขอต้องใช้หากคุณต้องการกรองมิติข้อมูลในคำขอการรายงาน Pivot ซึ่งคล้ายกับฟังก์ชันการทำงานของการรายงานหลัก

การจัดเรียง

คุณสามารถควบคุมลักษณะการทำงานของการจัดเรียงของคําค้นหารายงาน Pivot สําหรับ Pivot แต่ละรายการ ได้โดยใช้ช่อง orderBys ของออบเจ็กต์ Pivot ซึ่งมีรายการออบเจ็กต์ OrderBy

OrderBy ทุกรายการสามารถมีรายการใดรายการหนึ่งต่อไปนี้

  • DimensionOrderBy, จัดเรียงผลลัพธ์ตามค่าของมิติข้อมูล
  • MetricOrderBy จัดเรียง ผลลัพธ์ตามค่าของเมตริก
  • PivotOrderBy ใช้ใน คําค้นหา Pivot และจัดเรียงผลลัพธ์ตามค่าของเมตริก ภายในกลุ่มคอลัมน์ Pivot

ตัวอย่างนี้แสดงข้อมูลโค้ดสําหรับคําจํากัดความ Pivot ที่หมุนรายงานในมิติข้อมูล browser โดยจัดเรียงผลลัพธ์ตามเมตริก sessions จากมากไปน้อย

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

การตอบกลับของรายงาน

การตอบกลับของรายงาน Pivot จากคำขอ API รายงาน Pivot ส่วนใหญ่ประกอบด้วยส่วนหัวและแถว

ส่วนหัวการตอบกลับ

ส่วนหัวของรายงาน Pivot ประกอบด้วย PivotHeaders, DimensionHeaders และ MetricHeaders ซึ่งแสดงคอลัมน์ใน รายงาน Pivot

ตัวอย่างเช่น รายงานที่มีมิติข้อมูล Pivot 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"
    }
  ],
  ...

}

แผนภูมิต่อไปนี้แสดงบทบาทของคอมโพเนนต์แต่ละรายการของการตอบกลับของรายงาน Pivot ในการแสดงผลรายงาน Pivot

ตารางข้อมูลดิบ

แถวการตอบกลับ

การตอบกลับของรายงาน Pivot จากเมธอด runPivotReport และ batchRunPivotReports แตกต่างจากการตอบกลับของเมธอดการรายงานหลัก เช่น runReport และ batchRunReports ตรงที่ แถวการตอบกลับของรายงาน Pivot แต่ละแถวแสดงถึงเซลล์เดียวของ ตาราง ในขณะที่รายงานปกติ แถวการตอบกลับเดียวจะแสดงถึงบรรทัด ตารางที่สมบูรณ์

ตัวอย่างต่อไปนี้แสดงส่วนหนึ่งของการตอบกลับของรายงาน Pivot สำหรับคําค้นหาที่มีมิติข้อมูล Pivot browser, country และ language รวมถึงเมตริก sessions ระบบจะแสดงผลเซลล์แต่ละเซลล์ของรายงาน Pivot แยกกัน

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

  ]

ข้อมูลนี้สอดคล้องกับเซลล์ 2 เซลล์ที่ไฮไลต์ในตารางต่อไปนี้

ตารางข้อมูลดิบ

ไลบรารีของไคลเอ็นต์

ดูคำอธิบายเกี่ยวกับ วิธีติดตั้งและกำหนดค่าไลบรารีของไคลเอ็นต์ได้ในคู่มือเริ่มใช้งานฉบับย่อ

ตัวอย่างต่อไปนี้ใช้ไลบรารีของไคลเอ็นต์เพื่อเรียกใช้คําค้นหา Pivot เพื่อสร้างรายงานจำนวนเซสชันตามประเทศ โดยหมุนตามมิติข้อมูลเบราว์เซอร์

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 = '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);
      });
    });
  }

แอปพลิเคชันเดโม

ดูตัวอย่างวิธีสร้างและแสดงรายงาน Pivot โดยใช้ JavaScript ได้ที่ แอปพลิเคชัน เดโมรายงาน Pivot ของ Google Analytics API v1

เนื้อหาของหน้าเว็บนี้ได้รับอนุญาตภายใต้ใบอนุญาตที่ต้องระบุที่มาของครีเอทีฟคอมมอนส์ 4.0 และตัวอย่างโค้ดได้รับอนุญาตภายใต้ใบอนุญาต Apache 2.0 เว้นแต่จะระบุไว้เป็นอย่างอื่น โปรดดูรายละเอียดที่นโยบายเว็บไซต์ Google Developers Java เป็นเครื่องหมายการค้าจดทะเบียนของ Oracle และ/หรือบริษัทในเครือ

อัปเดตล่าสุด 2026-08-12 UTC