นี่คือภาพรวมของความสามารถเมธอด API การรายงานแบบเรียลไทม์ของ Google Analytics Data API v1 สำหรับข้อมูลอ้างอิง API โดยละเอียด โปรดดูเอกสารอ้างอิง API
เหตุการณ์จะปรากฏในรายงานแบบเรียลไทม์ในไม่กี่วินาทีหลังจากที่มีการส่งเหตุการณ์นั้นไปยัง Google Analytics รายงานแบบเรียลไทม์จะแสดงเหตุการณ์และข้อมูลการใช้งานในช่วงเวลาตั้งแต่ปัจจุบันจนถึง 30 นาทีที่ผ่านมา (สูงสุด 60 นาทีสำหรับพร็อพเพอร์ตี้ Google Analytics 360) และสามารถใช้กับแอปพลิเคชันต่างๆ เช่น ตัวนับแบบเรียลไทม์ของผู้เข้าชมในเว็บไซต์ของคุณ
รายงานแบบเรียลไทม์รองรับมิติข้อมูลและเมตริกเพียงบางส่วนเมื่อเทียบกับฟังก์ชันการรายงานหลักของ Data API v1
ฟีเจอร์ที่แชร์กับรายงานหลัก
คำขอรายงานแบบเรียลไทม์มีความหมายเหมือนกับคำขอรายงานหลักสำหรับฟีเจอร์ที่ใช้ร่วมกันหลายรายการ ตัวอย่างเช่น การใส่เลขหน้า ตัวกรองมิติข้อมูล และพร็อพเพอร์ตี้ผู้ใช้ จะทำงานเหมือนกับรายงานหลักในรายงานแบบเรียลไทม์ โปรดทำความคุ้นเคยกับ ภาพรวมของฟังก์ชันการรายงานหลักของ Data API เวอร์ชัน 1 เนื่องจากส่วนที่เหลือของเอกสารนี้จะเน้นที่ฟีเจอร์เฉพาะสำหรับคำขอรายงานแบบเรียลไทม์
คำขอรายงาน
หากต้องการขอรายงานแบบเรียลไทม์ ก็สร้างออบเจ็กต์ RunRealtimeReportRequest ได้ เราขอแนะนำให้เริ่มต้นด้วยพารามิเตอร์คำขอเหล่านี้
- ข้อมูลที่ถูกต้องอย่างน้อย 1 รายการในช่องมิติข้อมูล
- ข้อมูลที่ถูกต้องอย่างน้อย 1 รายการในช่องmetrics
ต่อไปนี้เป็นคำขอตัวอย่างพร้อมฟิลด์ที่แนะนำ
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }]
}
Java
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient;
import com.google.analytics.data.v1beta.Dimension;
import com.google.analytics.data.v1beta.DimensionHeader;
import com.google.analytics.data.v1beta.Metric;
import com.google.analytics.data.v1beta.MetricHeader;
import com.google.analytics.data.v1beta.Row;
import com.google.analytics.data.v1beta.RunRealtimeReportRequest;
import com.google.analytics.data.v1beta.RunRealtimeReportResponse;
/**
* Google Analytics Data API sample application demonstrating the creation of a realtime report.
*
* <p>See
* https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport
* for more information.
*
* <p>Before you start the application, please review the comments starting with "TODO(developer)"
* and update the code to use correct values.
*
* <p>To run this sample using Maven:
*
* <pre>{@code
* cd google-analytics-data
* mvn compile exec:java -Dexec.mainClass="com.google.analytics.data.samples.RunRealtimeReportSample"
* }</pre>
*/
public class RunRealtimeReportSample {
public static void main(String... args) throws Exception {
// TODO(developer): Replace with your Google Analytics 4 property ID before running the sample.
String propertyId = "YOUR-GA4-PROPERTY-ID";
sampleRunRealtimeReport(propertyId);
}
// Runs a realtime report on a Google Analytics 4 property.
static void sampleRunRealtimeReport(String propertyId) throws Exception {
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
RunRealtimeReportRequest request =
RunRealtimeReportRequest.newBuilder()
.setProperty("properties/" + propertyId)
.addDimensions(Dimension.newBuilder().setName("country"))
.addMetrics(Metric.newBuilder().setName("activeUsers"))
.build();
// Make the request.
RunRealtimeReportResponse response = analyticsData.runRealtimeReport(request);
printRunRealtimeReportResponse(response);
}
}
// Prints results of a runRealReport call.
static void printRunRealtimeReportResponse(RunRealtimeReportResponse response) {
System.out.printf("%s rows received%n", response.getRowsList().size());
for (DimensionHeader header : response.getDimensionHeadersList()) {
System.out.printf("Dimension header name: %s%n", header.getName());
}
for (MetricHeader header : response.getMetricHeadersList()) {
System.out.printf("Metric header name: %s (%s)%n", header.getName(), header.getType());
}
System.out.println("Report result:");
for (Row row : response.getRowsList()) {
System.out.printf(
"%s, %s%n", row.getDimensionValues(0).getValue(), row.getMetricValues(0).getValue());
}
}
}
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
Dimension,
Metric,
RunRealtimeReportRequest,
)
from run_report import print_run_report_response
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_realtime_report(property_id)
def run_realtime_report(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a realtime report on a Google Analytics 4 property."""
client = BetaAnalyticsDataClient()
request = RunRealtimeReportRequest(
property=f"properties/{property_id}",
dimensions=[Dimension(name="country")],
metrics=[Metric(name="activeUsers")],
)
response = client.run_realtime_report(request)
print_run_report_response(response)
รายงานคำตอบ
การตอบกลับรายงานแบบเรียลไทม์ของคำขอ API จะเป็นส่วนหัวและแถวเป็นหลัก ส่วนหัวประกอบด้วย DimensionHeaders และ MetricHeaders ซึ่งแสดงคอลัมน์ในรายงาน แต่ละแถวจะประกอบด้วย DimensionValues และ MetricValues สำหรับคอลัมน์ในรายงาน ลำดับของคอลัมน์ในคำขอ ส่วนหัว และทุกแถวจะมีความสอดคล้องกัน
ตัวอย่างการตอบกลับสำหรับคำขอตัวอย่างข้างต้น
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "2541"
}
]
},
{
"dimensionValues": [
{
"value": "France"
}
],
"metricValues": [
{
"value": "12"
}
]
}
],
"rowCount": 2
}
ขนาด
มิติข้อมูลจะอธิบายและจัดกลุ่มข้อมูลเหตุการณ์สำหรับเว็บไซต์หรือแอปของคุณ เช่น มิติข้อมูล city จะระบุเมือง ("ปารีส" หรือ "นิวยอร์ก") ที่เป็นแหล่งที่มาของแต่ละเหตุการณ์ ในคำขอรายงาน คุณสามารถระบุมิติข้อมูลตั้งแต่ 0 รายการขึ้นไป ดูรายการชื่อมิติข้อมูล API ทั้งหมดที่มีอยู่ในคำขอแบบเรียลไทม์ได้ในมิติข้อมูลแบบเรียลไทม์
ตัวอย่างเช่น คำขอนี้จะจัดกลุ่มผู้ใช้ที่ใช้งานอยู่เป็นคอลัมน์มิติข้อมูล 2 คอลัมน์ ดังนี้
HTTP
POST https://analyticsdata.googleapis.com/v1beta/property/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [
{
"name": "country"
},
{
"name": "city"
}
],
"metrics": [{ "name": "activeUsers" }]
}
Java
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient;
import com.google.analytics.data.v1beta.Dimension;
import com.google.analytics.data.v1beta.Metric;
import com.google.analytics.data.v1beta.RunRealtimeReportRequest;
import com.google.analytics.data.v1beta.RunRealtimeReportResponse;
/**
* Google Analytics Data API sample application demonstrating the creation of a realtime report.
*
* <p>See
* https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport
* for more information.
*
* <p>Before you start the application, please review the comments starting with "TODO(developer)"
* and update the code to use correct values.
*
* <p>To run this sample using Maven:
*
* <pre>{@code
* cd google-analytics-data
* mvn compile exec:java -Dexec.mainClass="com.google.analytics.data.samples.RunRealtimeReportWithMultipleDimensionsSample"
* }</pre>
*/
public class RunRealtimeReportWithMultipleDimensionsSample {
public static void main(String... args) throws Exception {
// TODO(developer): Replace with your Google Analytics 4 property ID before running the sample.
String propertyId = "YOUR-GA4-PROPERTY-ID";
sampleRunRealtimeReportWithMultipleDimensions(propertyId);
}
// Runs a realtime report on a Google Analytics 4 property.
static void sampleRunRealtimeReportWithMultipleDimensions(String propertyId) throws Exception {
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
RunRealtimeReportRequest request =
RunRealtimeReportRequest.newBuilder()
.setProperty("properties/" + propertyId)
.addDimensions(Dimension.newBuilder().setName("country"))
.addDimensions(Dimension.newBuilder().setName(("city")))
.addMetrics(Metric.newBuilder().setName("activeUsers"))
.build();
// Make the request.
RunRealtimeReportResponse response = analyticsData.runRealtimeReport(request);
// Prints the response using a method in RunRealtimeReportSample.java
RunRealtimeReportSample.printRunRealtimeReportResponse(response);
}
}
}
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
Dimension,
Metric,
RunRealtimeReportRequest,
)
from run_report import print_run_report_response
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_realtime_report_with_multiple_dimensions(property_id)
def run_realtime_report_with_multiple_dimensions(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a realtime report on a Google Analytics 4 property."""
client = BetaAnalyticsDataClient()
request = RunRealtimeReportRequest(
property=f"properties/{property_id}",
dimensions=[Dimension(name="country"), Dimension(name="city")],
metrics=[Metric(name="activeUsers")],
)
response = client.run_realtime_report(request)
print_run_report_response(response)
ตัวอย่างเช่น แถวในการตอบกลับของรายงานอาจมีข้อมูลต่อไปนี้ แถวนี้หมายความว่ามีผู้ใช้ที่ใช้งานอยู่ 47 คนสำหรับเว็บไซต์หรือแอปของคุณที่มีเหตุการณ์จากเคปทาวน์ แอฟริกาใต้ในช่วง 30 นาทีที่ผ่านมา
"rows": [
...
{
"dimensionValues": [
{
"value": "South Africa"
},
{
"value": "Cape Town"
}
],
"metricValues": [
{
"value": "47"
}
]
},
...
],
เมตริก
เมตริกคือการวัดเชิงปริมาณของข้อมูลเหตุการณ์สำหรับเว็บไซต์หรือแอป ในคำขอรายงาน คุณสามารถระบุเมตริกได้อย่างน้อย 1 รายการ ดูรายการชื่อเมตริก API ทั้งหมดที่มีอยู่ในคำขอได้ในเมตริกแบบเรียลไทม์
ตัวอย่างเช่น คําขอนี้จะแสดงเมตริก 2 รายการที่จัดกลุ่มตามมิติข้อมูล unifiedScreenName ดังนี้
HTTP
POST https://analyticsdata.googleapis.com/v1beta/property/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "unifiedScreenName" }],
"metrics": [
{
"name": "screenPageViews"
},
{
"name": "conversions"
}
],
}
Java
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient;
import com.google.analytics.data.v1beta.Dimension;
import com.google.analytics.data.v1beta.Metric;
import com.google.analytics.data.v1beta.RunRealtimeReportRequest;
import com.google.analytics.data.v1beta.RunRealtimeReportResponse;
/**
* Google Analytics Data API sample application demonstrating the creation of a realtime report.
*
* <p>See
* https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport
* for more information.
*
* <p>Before you start the application, please review the comments starting with "TODO(developer)"
* and update the code to use correct values.
*
* <p>To run this sample using Maven:
*
* <pre>{@code
* cd google-analytics-data
* mvn compile exec:java -Dexec.mainClass="com.google.analytics.data.samples.RunRealtimeReportWithMultipleMetricsSample"
* }</pre>
*/
public class RunRealtimeReportWithMultipleMetricsSample {
public static void main(String... args) throws Exception {
// TODO(developer): Replace with your Google Analytics 4 property ID before running the sample.
String propertyId = "YOUR-GA4-PROPERTY-ID";
sampleRunRealtimeReportWithMultipleMetrics(propertyId);
}
// Runs a realtime report on a Google Analytics 4 property.
static void sampleRunRealtimeReportWithMultipleMetrics(String propertyId) throws Exception {
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
RunRealtimeReportRequest request =
RunRealtimeReportRequest.newBuilder()
.setProperty("properties/" + propertyId)
.addDimensions(Dimension.newBuilder().setName("unifiedScreenName"))
.addMetrics(Metric.newBuilder().setName(("screenPageViews")))
.addMetrics(Metric.newBuilder().setName("conversions"))
.build();
// Make the request.
RunRealtimeReportResponse response = analyticsData.runRealtimeReport(request);
// Prints the response using a method in RunRealtimeReportSample.java
RunRealtimeReportSample.printRunRealtimeReportResponse(response);
}
}
}
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
Dimension,
Metric,
RunRealtimeReportRequest,
)
from run_report import print_run_report_response
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_realtime_report_with_multiple_metrics(property_id)
def run_realtime_report_with_multiple_metrics(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a realtime report on a Google Analytics 4 property."""
client = BetaAnalyticsDataClient()
request = RunRealtimeReportRequest(
property=f"properties/{property_id}",
dimensions=[Dimension(name="unifiedScreenName")],
metrics=[Metric(name="screenPageViews"), Metric(name="conversions")],
)
response = client.run_realtime_report(request)
print_run_report_response(response)
ตัวอย่างเช่น แถวในคำตอบของรายงานอาจมีข้อมูลต่อไปนี้ แถวนี้หมายความว่าชื่อหน้า (เว็บ) หรือชื่อหน้าจอ (แอป) ของ main_menu มียอดดู 257 ครั้งและเหตุการณ์ Conversion 72 ครั้งในช่วง 30 นาทีที่ผ่านมา
"rows": [
...
{
"dimensionValues": [
{
"value": "main_menu"
}
],
"metricValues": [
{
"value": "257"
},
{
"value": "72"
}
]
},
...
],
ช่วงนาที
ในคำขอรายงานแบบเรียลไทม์ คุณสามารถใช้ช่อง minuteRanges เพื่อระบุช่วงนาทีของข้อมูลเหตุการณ์ที่จะอ่านได้ โดยการค้นหาสามารถใช้ช่วงนาทีที่แยกกันได้สูงสุด 2 ช่วง หากไม่มีการระบุข้อกำหนดช่วงนาทีในการค้นหา ระบบจะใช้ช่วงนาทีเดียวสำหรับ 30 นาทีที่ผ่านมา
เช่น คำขอด้านล่างจะแสดงจำนวนผู้ใช้ที่ใช้งานอยู่สำหรับช่วงนาทีที่แยกกัน 2 ช่วง ดังนี้
- ช่วงที่ 1: เริ่มตั้งแต่ 4 นาทีที่ผ่านมาจนถึงช่วงเวลาปัจจุบัน
ช่วงที่ 2: เริ่มตั้งแต่ 29 นาทีที่ผ่านมาจนถึง 25 นาทีที่ผ่านมา (รวม)
HTTP
POST https://analyticsdata.googleapis.com/v1beta/property/GA4_PROPERTY_ID:runRealtimeReport
{
"metrics": [
{
"name": "activeUsers"
}
],
"minuteRanges": [
{
"name": "0-4 minutes ago",
"startMinutesAgo": 4,
},
{
"name": "25-29 minutes ago",
"startMinutesAgo": 29,
"endMinutesAgo": 25,
}
],
}
Java
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient;
import com.google.analytics.data.v1beta.Metric;
import com.google.analytics.data.v1beta.MinuteRange;
import com.google.analytics.data.v1beta.RunRealtimeReportRequest;
import com.google.analytics.data.v1beta.RunRealtimeReportResponse;
/**
* Google Analytics Data API sample application demonstrating the creation of a realtime report.
*
* <p>See
* https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport
* for more information.
*
* <p>Before you start the application, please review the comments starting with "TODO(developer)"
* and update the code to use correct values.
*
* <p>To run this sample using Maven:
*
* <pre>{@code
* cd google-analytics-data
* mvn compile exec:java -Dexec.mainClass="com.google.analytics.data.samples.RunRealtimeReportWithMinuteRangesSample"
* }</pre>
*/
public class RunRealtimeReportWithMinuteRangesSample {
public static void main(String... args) throws Exception {
// TODO(developer): Replace with your Google Analytics 4 property ID before running the sample.
String propertyId = "YOUR-GA4-PROPERTY-ID";
sampleRunRealtimeReportWithMinuteRanges(propertyId);
}
// Runs a realtime report on a Google Analytics 4 property.
static void sampleRunRealtimeReportWithMinuteRanges(String propertyId) throws Exception {
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
RunRealtimeReportRequest request =
RunRealtimeReportRequest.newBuilder()
.setProperty("properties/" + propertyId)
.addMetrics(Metric.newBuilder().setName(("activeUsers")))
.addMinuteRanges(
MinuteRange.newBuilder().setName("0-4 minutes ago").setStartMinutesAgo(4))
.addMinuteRanges(
MinuteRange.newBuilder()
.setName("25-29 minutes ago")
.setEndMinutesAgo(29)
.setEndMinutesAgo(25))
.build();
// Make the request.
RunRealtimeReportResponse response = analyticsData.runRealtimeReport(request);
// Prints the response using a method in RunRealtimeReportSample.java
RunRealtimeReportSample.printRunRealtimeReportResponse(response);
}
}
}
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
Metric,
MinuteRange,
RunRealtimeReportRequest,
)
from run_report import print_run_report_response
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_realtime_report_with_minute_ranges(property_id)
def run_realtime_report_with_minute_ranges(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a realtime report on a Google Analytics 4 property. Dimensions
field is omitted in the query, which results in total values of active users
returned for each minute range in the report.
Note the `dateRange` dimension added to the report response automatically
as a result of querying multiple minute ranges.
"""
client = BetaAnalyticsDataClient()
request = RunRealtimeReportRequest(
property=f"properties/{property_id}",
metrics=[Metric(name="activeUsers")],
minute_ranges=[
MinuteRange(name="0-4 minutes ago", start_minutes_ago=4),
MinuteRange(
name="25-29 minutes ago", start_minutes_ago=29, end_minutes_ago=25
),
],
)
response = client.run_realtime_report(request)
print_run_report_response(response)
ด้านล่างนี้เป็นคำตอบตัวอย่างที่สมบูรณ์สำหรับการค้นหาด้านล่าง โปรดทราบว่ามิติข้อมูล dateRange ที่เพิ่มลงในการตอบสนองของรายงานโดยอัตโนมัติอันเป็นผลมาจากการค้นหาหลายช่วงนาที
{
"dimensionHeaders": [
{
"name": "dateRange"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "0-4 minutes ago"
}
],
"metricValues": [
{
"value": "16"
}
]
},
{
"dimensionValues": [
{
"value": "25-29 minutes ago"
}
],
"metricValues": [
{
"value": "14"
}
]
}
],
"rowCount": 2,
"kind": "analyticsData#runRealtimeReport"
}