ภาพรวม

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

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

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

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

ตารางข้อมูล Pivot

ฟีเจอร์ที่ใช้ร่วมกับรายงาน Core

คำขอการรายงาน Pivot มีความหมายเหมือนกับคำขอรายงาน Core สำหรับฟีเจอร์ที่ใช้ร่วมกันหลายรายการ ตัวอย่างเช่น การแบ่งหน้า ตัวกรองมิติข้อมูล และพร็อพเพอร์ตี้ผู้ใช้จะทํางานในรายงาน 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 เป็น Pivot โปรดสังเกตวิธีที่การค้นหาใช้ช่อง 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 Report Response ในการแสดงผลรายงาน 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 เพื่อสร้างรายงานจํานวนเซสชันตามประเทศ โดยใช้มิติข้อมูลเบราว์เซอร์เป็น 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 ของ Google Analytics API v1 เพื่อดูตัวอย่างวิธีสร้างและแสดงรายงาน Pivot โดยใช้ JavaScript