นี่คือคู่มือนักพัฒนาซอฟต์แวร์เกี่ยวกับ Analytics Reporting API v4 สำหรับข้อมูลอ้างอิงโดยละเอียดของ API โปรดดูเอกสารอ้างอิง API
รายงาน
Analytics Reporting API v4 ให้เมธอด batchGet
เพื่อเข้าถึงทรัพยากรรายงาน
ส่วนต่อไปนี้จะอธิบายโครงสร้างของเนื้อหาคำขอสำหรับ batchGet
และโครงสร้างของเนื้อหาการตอบกลับจาก batchGet
เนื้อความของคำขอ
หากต้องการใช้ Analytics Reporting API v4 เพื่อขอข้อมูล คุณต้องสร้างออบเจ็กต์ ReportRequest ซึ่งมีข้อกำหนดขั้นต่ำดังต่อไปนี้
- รหัสข้อมูลพร็อพเพอร์ตี้ที่ถูกต้องสำหรับช่อง viewId
- ข้อมูลที่ถูกต้องอย่างน้อย 1 รายการในช่อง dateRanges
- ข้อมูลที่ถูกต้องอย่างน้อย 1 รายการในช่องmetrics
หากต้องการค้นหารหัสข้อมูลพร็อพเพอร์ตี้ ให้ค้นหาในเมธอดสรุปบัญชีหรือใช้โปรแกรมสำรวจบัญชี
หากไม่ได้ระบุช่วงวันที่ ช่วงวันที่เริ่มต้นจะเป็น {"startDate": "7daysAgo", "endDate": "yesterday"}
ต่อไปนี้เป็นตัวอย่างคำขอที่มีช่องที่ต้องกรอกขั้นต่ำ
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:users"}]
}
]
}
เมธอด batchGet
ยอมรับออบเจ็กต์ ReportRequest สูงสุด 5 รายการ คำขอทั้งหมดควรมี
dateRange
,
viewId
,
segments
,
samplingLevel
และ cohortGroup
เหมือนกัน
เนื้อหาการตอบกลับ
เนื้อหาการตอบกลับของคำขอ API คืออาร์เรย์ของออบเจ็กต์รายงาน โครงสร้างรายงานจะกำหนดในออบเจ็กต์ ColumnHeader ซึ่งอธิบายมิติข้อมูลและเมตริก และประเภทข้อมูลในรายงาน ค่าของมิติข้อมูลและเมตริกจะระบุอยู่ในช่องข้อมูล
ตัวอย่างการตอบกลับสำหรับคำขอตัวอย่างข้างต้น
{
"reports": [
{
"columnHeader": {
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:users",
"type": "INTEGER"
}
]
}
},
"data": {
"isDataGolden": true,
"maximums": [
{
"values": [
"98"
]
}
],
"minimums": [
{
"values": [
"98"
]
}
],
"rowCount": 1,
"rows": [
{
"metrics": [
{
"values": [
"98"
]
}
]
}
],
"totals": [
{
"values": [
"98"
]
}
]
}
}
]
}
เมตริก
เมตริกคือการวัดเชิงปริมาณ โดยทุกคำขอต้องมีออบเจ็กต์เมตริกอย่างน้อย 1 รายการ
ในตัวอย่างต่อไปนี้ ระบบจะใช้เมตริก Sessions
กับเมธอด batchGet
เพื่อหาจํานวนเซสชันทั้งหมดในช่วงวันที่ที่ระบุ
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:sessions"}]
}
]
}
คุณใช้เครื่องมือสำรวจมิติข้อมูลและเมตริกหรือ API ข้อมูลเมตาเพื่อดูรายการมิติข้อมูลและเมตริกที่ใช้ได้
การกรอง
เมื่อส่งคำขอ batchGet
คุณจะขอให้ส่งคำขอแสดงเฉพาะเมตริกที่ตรงกับเกณฑ์ที่ต้องการได้ หากต้องการกรองเมตริก ในส่วนเนื้อหาของคำขอ ให้ระบุ MetricFilterClauses อย่างน้อย 1 รายการ และใน MetricFilterClause
แต่ละรายการ ให้กำหนด MetricFilters อย่างน้อย 1 รายการ
ใน MetricFilter
แต่ละรายการ ให้ระบุค่าสำหรับรายการต่อไปนี้
metricName
not
operator
comparisonValue
ให้ {metricName}
แทนเมตริก {operator}
operator
และ
{comparisonValue}
comparisonValue
จากนั้นตัวกรองจะทำงานดังนี้
if {metricName} {operator} {comparisonValue}
return the metric
หากคุณระบุ true
สำหรับ not
ตัวกรองจะทำงานดังนี้
if {metricName} {operator} {comparisonValue}
do not return the metric
ในตัวอย่างต่อไปนี้ batchGet
จะแสดงเฉพาะการดูหน้าเว็บที่มีค่ามากกว่า 2
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"metricFilterClauses": [{
"filters": [{
"metricName": "ga:pageviews",
"operator": "GREATER_THAN",
"comparisonValue": "2"
}]
}]
}]
}
นิพจน์
นิพจน์เมตริกคือนิพจน์ทางคณิตศาสตร์ที่คุณกำหนดในเมตริกที่มีอยู่ ซึ่งทำงานเหมือนกับเมตริกที่คำนวณแล้วแบบไดนามิก คุณกำหนดชื่อแทนเพื่อแสดงถึงนิพจน์เมตริกได้ เช่น
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{
"expression": "ga:goal1completions/ga:users",
"alias": "completions per user"
}
]
}
]
}
การเรียงลำดับ
วิธีจัดเรียงผลลัพธ์ตามค่าเมตริก
- ระบุชื่อหรือชื่อแทนในช่อง
fieldName
- ระบุลำดับการจัดเรียง (
ASCENDING
หรือDESCENDING
) ผ่านช่องsortOrder
ในตัวอย่างต่อไปนี้ batchGet
จะแสดงผลเมตริกที่จัดเรียงตามเซสชันก่อน แล้วจึงจัดเรียงตามการดูหน้าเว็บในลำดับจากมากไปน้อย
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"orderBys":
[
{"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
{"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
]
}
]
}
ขนาด
มิติข้อมูลจะอธิบายลักษณะของผู้ใช้ เซสชันและการทำงานของผู้ใช้
ตัวอย่างเช่น มิติข้อมูลเมืองจะอธิบายลักษณะของเซสชันและระบุเมือง ("ปารีส" หรือ "นิวยอร์ก") ที่แต่ละเซสชันเกิดขึ้น
ในคำขอ batchGet
คุณระบุออบเจ็กต์มิติข้อมูลได้ตั้งแต่ 0 รายการขึ้นไป เช่น
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges":
[
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics":
[
{"expression": "ga:users"}
],
"dimensions":
[
{"name": "ga:city"}
]
}
]
}
การกรอง
เมื่อส่งคำขอ batchGet
คุณขอให้ส่งคำขอดังกล่าวแสดงเฉพาะมิติข้อมูลที่ตรงตามเกณฑ์ที่ระบุได้ หากต้องการกรองมิติข้อมูล ในส่วนเนื้อหาของคำขอ ให้ระบุ DimensionsFilterClauses อย่างน้อย 1 รายการ และใน DimensionsFilterClause
แต่ละรายการ ให้กำหนดDimensionsFiltersอย่างน้อย 1 รายการ
ใน DimensionsFilters
แต่ละรายการ ให้ระบุค่าสำหรับรายการต่อไปนี้
dimensionName
not
operator
expressions
caseSensitive
ให้ {dimensionName}
แสดงถึงมิติข้อมูล {operator}
operator
และ {expressions}
expressions
จากนั้นตัวกรองจะทำงานดังนี้
if {dimensionName} {operator} {expressions}
return the dimension
หากคุณระบุ true
สำหรับ not
ตัวกรองจะทำงานดังนี้
if {dimensionName} {operator} {expressions}
do not return the dimension
ในตัวอย่างต่อไปนี้ batchGet
จะแสดงผลการดูหน้าเว็บและเซสชันในเบราว์เซอร์ Chrome
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Chrome"]
}
]
}
]
}
]
}
การเรียงลำดับ
วิธีจัดเรียงผลลัพธ์ตามค่ามิติข้อมูล
เช่น batchGet
ต่อไปนี้จะแสดงมิติข้อมูลที่จัดเรียงตามประเทศ จากนั้นแสดงตามเบราว์เซอร์
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
"orderBys": [
{"fieldName": "ga:country"},
{"fieldName": "ga:browser"}
]
}
]
}
ที่เก็บข้อมูลฮิสโตแกรม
สำหรับมิติข้อมูลที่มีค่าจำนวนเต็ม คุณจะเข้าใจลักษณะต่างๆ ของมิติข้อมูลได้ง่ายขึ้นโดยการจัดเก็บค่าไว้เป็นช่วง ใช้ช่อง histogramBuckets
เพื่อกำหนดช่วงสำหรับที่เก็บข้อมูลผลลัพธ์และระบุ HISTOGRAM_BUCKET
เป็นประเภทคำสั่งซื้อ เช่น
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [
{
"name": "ga:sessionCount",
"histogramBuckets": ["1","10","100","200","400"]
}
],
"orderBys": [
{
"fieldName": "ga:sessionCount",
"orderType": "HISTOGRAM_BUCKET"
}
]
}
]
}
ช่วงวันที่หลายช่วง
Google Analytics Reporting API v4 ช่วยให้คุณรับข้อมูลในช่วงวันที่หลายช่วงในคำขอเดียวได้ ไม่ว่าคำขอของคุณจะระบุช่วงวันที่ 1 หรือ 2 ช่วง ระบบจะแสดงผลข้อมูลในออบเจ็กต์ dateRangeValue เช่น
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}]
}
]
}
การสั่งซื้อเดลต้า
เมื่อขอค่าเมตริกในช่วงวันที่ 2 ช่วง คุณสามารถเรียงลำดับผลลัพธ์ตามความแตกต่างระหว่างค่าของเมตริกในช่วงวันที่ดังกล่าว เช่น
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}],
"orderBys": [
{
"fieldName": "ga:sessions",
"orderType": "DELTA"
}
]
}
]
}
ลักษณะการทำงานของมิติข้อมูลวันที่
หากคุณขอมิติข้อมูลที่เกี่ยวข้องกับวันที่และเวลา ออบเจ็กต์ DateRangeValue จะเก็บเฉพาะค่าของวันที่ที่อยู่ภายในช่วงที่เกี่ยวข้อง ส่วนค่าอื่นๆ ทั้งหมดที่ไม่ได้อยู่ในช่วงวันที่ที่ระบุจะเป็น 0
ตัวอย่างเช่น พิจารณาคำขอมิติข้อมูล ga:date
และเมตริก ga:sessions
ในช่วงวันที่ 2 ช่วง ได้แก่ มกราคมและกุมภาพันธ์
ในการตอบกลับสำหรับข้อมูลที่ขอในเดือนมกราคม ค่าในเดือนกุมภาพันธ์จะเป็น 0
และในการตอบกลับสำหรับข้อมูลที่ขอในเดือนกุมภาพันธ์ ค่าในเดือนมกราคมจะเป็น 0
รายงานเดือนมกราคม
{
"dimensions": [
"20140101" # `ga:date` dimension value for January 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"8"
]
},
{
"values": [ # February DateRangeValue.
"0"
]
}
]
},
...
รายงานเดือนกุมภาพันธ์
{
"dimensions": [
"20140201" # `ga:date` dimension value for February 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"0"
]
},
{
"values": [ # February DateRangeValue.
"7"
]
}
]
},
...
กลุ่ม
หากต้องการขอข้อมูล Analytics ชุดย่อย ให้ใช้กลุ่ม เช่น คุณอาจกำหนดผู้ใช้จากประเทศหรือเมืองหนึ่งๆ ไว้ในกลุ่มหนึ่ง และกําหนดผู้ใช้ที่เข้าชมบางส่วนของเว็บไซต์ในอีกกลุ่มหนึ่งโดยเฉพาะ ตัวกรองจะแสดงเฉพาะแถวที่ตรงตามเงื่อนไขเท่านั้น ขณะที่กลุ่มจะแสดงชุดย่อยของผู้ใช้ เซสชัน หรือเหตุการณ์ที่ตรงตามเงื่อนไขที่มีกลุ่มดังกล่าวอยู่
เมื่อส่งคำขอโดยใช้กลุ่ม โปรดตรวจสอบสิ่งต่อไปนี้
- ReportRequest
ทั้งหมดภายในเมธอด
batchGet
ต้องมีการกำหนดกลุ่มที่เหมือนกัน - คุณเพิ่ม
ga:segment
ลงในรายการมิติข้อมูล
เช่น
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
"metrics": [{"expression": "ga:sessions"}],
"segments": [
{
"dynamicSegment":
{
"name": "Sessions with Safari browser",
"userSegment":
{
"segmentFilters": [
{
"simpleSegment":
{
"orFiltersForSegment": [
{
"segmentFilterClauses": [
{
"dimensionFilter":
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Safari"]
}
}]
}]
}
}]
}
}
}]
}]
}
ดูตัวอย่างสำหรับตัวอย่างคำขอเพิ่มเติมที่มีกลุ่ม
รหัสกลุ่ม
ใช้ช่อง segmentId
เพื่อขอกลุ่ม
คุณไม่สามารถใช้ทั้ง segmentId
และ dynamicSegment
เพื่อขอกลุ่มได้
เช่น
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
"metrics": [{"expression": "ga:users"}],
"segments": [{"segmentId": "gaid::-3"}]
}
]
}
ทดสอบผลิตภัณฑ์
การสุ่มตัวอย่างอาจส่งผลต่อผลลัพธ์ของข้อมูลและเป็นสาเหตุที่พบบ่อยซึ่งทำให้ค่าที่แสดงผลจาก API ไม่ตรงกับอินเทอร์เฟซเว็บ ใช้ช่อง samplingLevel
เพื่อกำหนดขนาดตัวอย่างที่ต้องการ
- ตั้งค่าเป็น
SMALL
เพื่อการตอบสนองอย่างรวดเร็วในขนาดการสุ่มตัวอย่างที่เล็กลง - โปรดกำหนดค่าเป็น
LARGE
เพื่อการตอบสนองที่แม่นยำมากขึ้นแต่ช้าลง - กำหนดค่าเป็น
DEFAULT
สำหรับคำตอบที่รักษาสมดุลระหว่างความเร็วกับความแม่นยำ
เช่น
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}],
"metrics": [{"expression": "ga:sessions"}],
"samplingLevel": "LARGE"
}
]
}
หากรายงาน
มีข้อมูลจากการสุ่มตัวอย่าง Analytics Reporting API v4 จะแสดงช่อง samplesReadCounts
และ samplingSpaceSizes
หากผลลัพธ์ไม่ได้มาจากการสุ่มตัวอย่าง ระบบจะไม่กำหนดฟิลด์เหล่านี้
ด้านล่างคือตัวอย่างการตอบกลับซึ่งมีข้อมูลที่สุ่มตัวอย่างจากคำขอที่มีช่วงวันที่ 2 ช่วง ผลลัพธ์คำนวณจากตัวอย่างเกือบ 500,000 รายการของขนาดพื้นที่การสุ่มตัวอย่างประมาณ 15 ล้านเซสชัน ดังนี้
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
การใส่เลขหน้า
Analytics Reporting API v4 ใช้ช่อง pageToken
และ pageSize
เพื่อใส่เลขหน้าผ่านผลลัพธ์การตอบสนองที่ครอบคลุมหลายหน้า คุณได้รับ pageToken
จากพารามิเตอร์
nextPageToken
ในการตอบสนองคำขอ
reports.batchGet
:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
ขั้นตอนถัดไป
ตอนนี้คุณก็พูดถึงพื้นฐานของการสร้างรายงานแล้ว ลองมาดูฟีเจอร์ขั้นสูงของ API v4 กัน