Data API v1 ของ Google Analytics ช่วยให้คุณสร้างตาราง Pivot ได้ ตาราง Pivot เป็นเครื่องมือสรุปข้อมูลที่แสดงข้อมูลด้วยการจัดเรียงข้อมูลในตารางใหม่โดยการหมุนข้อมูลในมิติข้อมูลอย่างน้อย 1 รายการ
ตัวอย่างเช่น ลองพิจารณาตารางข้อมูลดิบต่อไปนี้
การใช้ข้อมูลนี้จะช่วยสร้างตาราง Pivot ได้ โดยจะแบ่งข้อมูลเซสชันตามเบราว์เซอร์ และเลือกมิติข้อมูลประเทศและภาษาเป็น Pivot เพิ่มเติม
ฟีเจอร์ที่ใช้ร่วมกันกับรายงานหลัก
คำขอการรายงานแบบหมุนมีลักษณะเดียวกันกับคำขอรายงานหลักสำหรับฟีเจอร์ที่ใช้ร่วมกันหลายรายการ ตัวอย่างเช่น การแบ่งหน้า ตัวกรองมิติข้อมูล และพร็อพเพอร์ตี้ผู้ใช้จะทํางานในรายงาน Pivot เหมือนกับในรายงานหลัก คู่มือนี้มุ่งเน้นที่ฟีเจอร์การรายงานแบบหมุน หากต้องการทำความคุ้นเคยกับฟังก์ชันการรายงานหลักของ Data API v1 โปรดอ่านคู่มือพื้นฐานการรายงาน และคู่มือกรณีการใช้งานขั้นสูง
วิธีการรายงานแบบหมุน
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 รายการในฟิลด์มิติข้อมูล
- รายการที่ถูกต้องอย่างน้อย 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 รองรับการหมุนหลายรายการตราบใดที่ผลคูณของพารามิเตอร์ 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
ของเนื้อหาคำขอ หากต้องการให้มิติข้อมูลเหล่านั้นปรากฏในรายงาน มิติข้อมูลเหล่านั้นต้องแสดงอยู่ในฟิลด์ 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 ในคำขอ
ต่อไปนี้คือข้อมูลโค้ดของการค้นหาที่ขอผลรวมสำหรับbrowserมิติข้อมูล Pivot
"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 ช่วยให้คุณระบุฟิลด์ขีดจํากัด
และออฟเซ็ตในออบเจ็กต์
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 ที่หมุนรายงานในมิติข้อมูล 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 เพื่อสร้างรายงานจำนวนเซสชันตามประเทศ โดย 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