นี่คือคู่มือนักพัฒนาซอฟต์แวร์เกี่ยวกับ API การรายงานของ Analytics v4 สำหรับข้อมูลอ้างอิงโดยละเอียดของ API โปรดดูเอกสารอ้างอิง API
รายงาน
Analytics Reporting API v4 ให้เมธอด batchGet
เพื่อเข้าถึงทรัพยากรรายงาน
ส่วนต่อไปนี้อธิบายโครงสร้างของเนื้อหาคำขอสำหรับ batchGet
และโครงสร้างของเนื้อหาการตอบกลับจาก batchGet
เนื้อความของคำขอ
หากต้องการใช้ Reporting API ของ Analytics 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"
}
]
}
]
}
ลักษณะการทำงานของมิติข้อมูลวันที่
หากคุณขอมิติข้อมูลที่เกี่ยวข้องกับ date or time ออบเจ็กต์ 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 กัน