ภาพรวม

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

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

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

หมายเหตุ: หากต้องการความช่วยเหลือเกี่ยวกับการย้ายข้อมูลโค้ดที่มีอยู่จาก Google Analytics Reporting API v4 (พร็อพเพอร์ตี้ Universal Analytics เท่านั้น) ไปยัง Google Analytics Data API v1 (พร็อพเพอร์ตี้ Google Analytics 4 เท่านั้น) โปรดดูคู่มือการย้ายข้อมูล

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

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

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

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

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

• batchRunPivotReports เป็นรูปแบบกลุ่มของเมธอด runPivotReport ซึ่งจะช่วยให้สร้างรายงานหลายฉบับได้โดยใช้การเรียก API เดียว

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

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

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

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

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

คำขอรายงาน Pivot

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

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

• รายการที่ถูกต้องในช่อง dateRanges
• ข้อมูลที่ถูกต้องอย่างน้อย 1 รายการในช่องมิติข้อมูล
• ข้อมูลที่ถูกต้องอย่างน้อย 1 รายการในช่องmetrics
• ข้อมูล Pivot ที่ถูกต้องอย่างน้อย 2 รายการในช่อง pivot

ต่อไปนี้เป็นคำขอตัวอย่างพร้อมฟิลด์ที่แนะนำ

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

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

ต้องกำหนดมิติข้อมูลในช่องมิติข้อมูลของเนื้อหาคำขอ หากต้องการให้แสดงในรายงาน มิติข้อมูลเหล่านั้นต้องแสดงอยู่ในช่อง fieldNames ของออบเจ็กต์ Pivot ด้วย มิติข้อมูลจะไม่ปรากฏในรายงานหากไม่ได้ใช้ใน Pivot ของ Query แบบ Pivot ไม่จำเป็นต้องแสดงมิติข้อมูลบางรายการใน fieldNames ของ Pivot คุณใช้มิติข้อมูลในตัวกรองได้โดยเฉพาะ และจะใช้มิติข้อมูลใน fieldNames ของ Pivot ไม่ได้

ด้านล่างนี้เป็นข้อมูลโค้ดที่สาธิตการใช้งานช่อง dimension และ fieldNames สำหรับตารางที่มีการหมุน 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 นั้นคล้ายกับวิธีการรายงานหลัก โดยให้คุณระบุช่องขีดจำกัดและออฟเซ็ตในออบเจ็กต์ Pivot เพื่อใช้การใส่เลขหน้า ระบบจะใช้การตั้งค่าการใส่เลขหน้ากับ 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 ที่ทำการ 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 เซลล์ที่ไฮไลต์ในตารางด้านล่าง

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

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

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

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

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

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