ภาพรวม

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

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

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

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

ตารางข้อมูลแบบแบ่งตามส่วน

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

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

วิธีการรายงาน 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

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

  • รายการที่ถูกต้องในช่อง dateRanges
  • มีรายการที่ถูกต้องอย่างน้อย 1 รายการในช่องมิติข้อมูล
  • มีรายการที่ถูกต้องอย่างน้อย 1 รายการในช่องเมตริก
  • รายการ 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 แต่ละรายการอธิบายถึงมิติข้อมูลที่มองเห็นได้ และแถวในการตอบสนองของรายงาน

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

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

    "pivots": [
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250,
        "orderBys": [
          {
            "dimension": {
              "dimensionName": "country"
            }
          }
        ]
      },
      {
        "fieldNames": [
          "browser"
        ],
        "offset": 3,
        "limit": 3,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      }
    ],
    ...

ขนาด

มิติข้อมูลจะอธิบายและจัดกลุ่มข้อมูลเหตุการณ์สำหรับ เว็บไซต์หรือแอป ตัวอย่างเช่น มิติข้อมูล city จะบ่งบอกถึงเมือง ("ปารีส" หรือ "New York") ซึ่งเป็นที่มาของแต่ละเหตุการณ์ ในคำขอรายงาน คุณสามารถ ระบุมิติข้อมูลเป็นศูนย์คำขึ้นไป

มิติข้อมูลต้องได้รับการกำหนดภายใน มิติข้อมูล ของเนื้อความคำขอ หากต้องการให้แสดงในรายงาน มิติข้อมูลเหล่านั้นต้อง แสดงอยู่ใน fieldNames ของออบเจ็กต์ Pivot มิติข้อมูลจะไม่แสดงในรายงาน หากไม่มีการนำไปใช้ใน คำสั่ง Pivot ของคำสั่ง Pivot บางมิติข้อมูลอาจไม่ได้แสดงอยู่ในแท็ก Pivot fieldNames มิติข้อมูลจะใช้ได้เฉพาะในตัวกรองเท่านั้น และไม่สามารถใช้ได้ใน 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",
    ]
  },
  ...

เมตริกที่คำนวณแล้วจะแสดงผลในผลรวม ของ 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 จะช่วยให้คุณ เพื่อระบุขีดจำกัด และ offset ในฟิลด์ ออบเจ็กต์ Pivot เพื่อใช้การใส่เลขหน้า การตั้งค่าการใส่เลขหน้าจะมีผลกับ Pivot แต่ละรายการแยกกัน ต้องระบุช่อง limit สำหรับออบเจ็กต์ Pivot ทุกรายการเพื่อจำกัด รายงาน Cardinality

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 ที่ทำการ Pivot ในรายงาน มิติข้อมูล browser เรียงลำดับผลลัพธ์ตามเมตริก sessions ใน จากมากไปน้อย

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

รายงานคำตอบ

การตอบกลับรายงาน Pivot ของ Pivot คำขอ API การรายงานมักเป็นส่วนหัวและแถว

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

ส่วนหัวของรายงาน 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 = 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

แอปพลิเคชันการสาธิต

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