Method: properties.runRealtimeReport
گزارشی سفارشی از دادههای رویداد بیدرنگ را برای دارایی شما برمیگرداند. رویدادها چند ثانیه پس از ارسال به Google Analytics در گزارشهای بلادرنگ ظاهر میشوند. گزارشهای بلادرنگ رویدادها و دادههای استفاده را برای دورههای زمانی از لحظه حال تا 30 دقیقه قبل نشان میدهند (تا 60 دقیقه برای خواص Google Analytics 360).
برای راهنمایی برای ساختن درخواستهای بلادرنگ و درک پاسخها، به ایجاد گزارش بیدرنگ مراجعه کنید.
درخواست HTTP
POST https://analyticsdata.googleapis.com/v1beta/{property=properties/*}:runRealtimeReport
URL از دستور GRPC Transcoding استفاده می کند.
پارامترهای مسیر
پارامترها |
---|
property | string شناسه دارایی Google Analytics GA4 که رویدادهای آن ردیابی می شوند. در مسیر URL و نه بدنه مشخص شده است. برای کسب اطلاعات بیشتر، ببینید شناسه ملک خود را از کجا پیدا کنید . مثال: خواص/1234 |
درخواست بدن
بدنه درخواست حاوی داده هایی با ساختار زیر است:
فیلدها |
---|
dimensions[] | object ( Dimension ) ابعاد درخواستی و نمایش داده شده |
metrics[] | object ( Metric ) معیارهای درخواست شده و نمایش داده شده |
dimensionFilter | object ( FilterExpression ) بند فیلتر ابعاد. معیارها را نمی توان در این فیلتر استفاده کرد. |
metricFilter | object ( FilterExpression ) بند فیلتر معیارها. در مرحله پس از تجمع، مشابه SQL دارای بند اعمال می شود. در این فیلتر نمی توان از ابعاد استفاده کرد. |
limit | string ( int64 format) تعداد ردیف هایی که باید برگردانده شوند. اگر مشخص نشده باشد، 10000 ردیف برگردانده می شود. API حداکثر 250000 سطر را در هر درخواست برمی گرداند، مهم نیست که چقدر درخواست کنید. limit باید مثبت باشد API همچنین میتواند ردیفهای کمتری را نسبت به limit درخواستی برگرداند، اگر مقادیر ابعاد به اندازه limit وجود نداشته باشد. به عنوان مثال، کمتر از 300 مقدار ممکن برای country بعد وجود دارد، بنابراین هنگام گزارش تنها country ، نمی توانید بیش از 300 ردیف دریافت کنید، حتی اگر limit روی مقدار بالاتر تنظیم کنید. |
metricAggregations[] | enum ( MetricAggregation ) تجمیع معیارها مقادیر متریک انبوه در ردیفهایی نشان داده میشوند که در آن dimensionValues روی "RESERVED_(MetricAggregation)" تنظیم شده است. |
orderBys[] | object ( OrderBy ) نحوه ترتیب ردیف ها در پاسخ را مشخص می کند. |
returnPropertyQuota | boolean وضعیت فعلی سهمیه همزمان این ویژگی Analytics را تغییر میدهد یا خیر. سهمیه در PropertyQuota برگردانده می شود. |
minuteRanges[] | object ( MinuteRange ) محدوده دقیقه از داده های رویداد برای خواندن. اگر مشخص نشده باشد، محدوده یک دقیقه برای 30 دقیقه آخر استفاده خواهد شد. اگر چندین محدوده دقیقه درخواست شود، هر سطر پاسخ حاوی یک شاخص محدوده دقیقه بر اساس صفر خواهد بود. اگر محدودههای دو دقیقهای همپوشانی داشته باشند، دادههای رویداد برای دقیقههای همپوشانی در ردیفهای پاسخ برای هر دو محدوده دقیقه گنجانده میشود. |
بدن پاسخگو
جدول گزارش بیدرنگ پاسخ مربوط به یک درخواست.
در صورت موفقیت آمیز بودن، بدنه پاسخ حاوی داده هایی با ساختار زیر است:
نمایندگی JSON |
---|
{
"dimensionHeaders": [
{
object (DimensionHeader )
}
],
"metricHeaders": [
{
object (MetricHeader )
}
],
"rows": [
{
object (Row )
}
],
"totals": [
{
object (Row )
}
],
"maximums": [
{
object (Row )
}
],
"minimums": [
{
object (Row )
}
],
"rowCount": integer,
"propertyQuota": {
object (PropertyQuota )
},
"kind": string
} |
فیلدها |
---|
dimensionHeaders[] | object ( DimensionHeader ) ستون های ابعاد را توصیف می کند. تعداد DimensionHeader و ترتیب DimensionHeaders با ابعاد موجود در ردیف ها مطابقت دارد. |
metricHeaders[] | object ( MetricHeader ) ستون های متریک را توصیف می کند. تعداد MetricHeader و ترتیب MetricHeaders با معیارهای موجود در ردیف ها مطابقت دارد. |
rows[] | object ( Row ) ردیف هایی از ترکیبات ارزش ابعاد و مقادیر متریک در گزارش. |
totals[] | object ( Row ) در صورت درخواست، مجموع مقادیر معیارها. |
maximums[] | object ( Row ) در صورت درخواست، حداکثر مقادیر معیارها. |
minimums[] | object ( Row ) در صورت درخواست، حداقل مقادیر معیارها. |
rowCount | integer تعداد کل ردیف ها در نتیجه پرس و جو. rowCount مستقل از تعداد سطرهای برگردانده شده در پاسخ و پارامتر limit درخواست است. به عنوان مثال اگر یک پرس و جو 175 ردیف را برمی گرداند و شامل limit 50 در درخواست API می شود، پاسخ شامل rowCount 175 اما فقط 50 ردیف خواهد بود. |
propertyQuota | object ( PropertyQuota ) وضعیت سهمیه بلادرنگ مالکیت Analytics شامل این درخواست است. |
kind | string مشخص می کند که این پیام چه نوع منبعی است. این kind همیشه رشته ثابت "analyticsData#runRealtimeReport" است. برای تمایز بین انواع پاسخ در JSON مفید است. |
محدوده مجوز
به یکی از حوزه های OAuth زیر نیاز دارد:
-
https://www.googleapis.com/auth/analytics.readonly
-
https://www.googleapis.com/auth/analytics
محدوده دقیقه
مجموعهای از دقیقههای پیوسته: startMinutesAgo
، startMinutesAgo + 1
، ...، endMinutesAgo
. درخواست ها تا محدوده 2 دقیقه مجاز هستند.
نمایندگی JSON |
---|
{
"name": string,
"startMinutesAgo": integer,
"endMinutesAgo": integer
} |
فیلدها |
---|
name | string یک نام به این محدوده دقیقه اختصاص می دهد. بعد dateRange با این نام در یک پاسخ گزارش ارزش گذاری می شود. در صورت تنظیم، نمی توان با date_range_ یا RESERVED_ شروع کرد. اگر تنظیم نشده باشد، محدودههای دقیقه با شاخص صفر آنها در درخواست نامگذاری میشوند: date_range_0 ، date_range_1 ، و غیره. |
startMinutesAgo | integer دقیقه شروع فراگیر برای پرس و جو به عنوان تعداد دقیقه قبل از این. به عنوان مثال، "startMinutesAgo": 29 مشخص می کند که گزارش باید شامل داده های رویداد از 29 دقیقه قبل و بعد باشد. نمی تواند بعد از endMinutesAgo باشد. اگر مشخص نشده باشد، startMinutesAgo به طور پیشفرض روی 29 تنظیم میشود. ویژگیهای استاندارد Analytics میتوانند حداکثر 30 دقیقه آخر دادههای رویداد را درخواست کنند ( startMinutesAgo <= 29 )، و ویژگیهای 360 Analytics میتوانند تا 60 دقیقه آخر دادههای رویداد را درخواست کنند ( startMinutesAgo <= 59 ). |
endMinutesAgo | integer دقیقه پایانی فراگیر برای پرس و جو به عنوان تعدادی دقیقه قبل از این. نمی تواند قبل از startMinutesAgo باشد. به عنوان مثال، "endMinutesAgo": 15 مشخص می کند که گزارش باید شامل داده های رویداد قبل از 15 دقیقه قبل باشد. اگر مشخص نشده باشد، endMinutesAgo به طور پیشفرض روی 0 تنظیم میشود. ویژگیهای استاندارد Analytics میتوانند هر دقیقه را در 30 دقیقه آخر داده رویداد ( endMinutesAgo <= 29 ) درخواست کنند، و ویژگیهای 360 Analytics میتوانند هر دقیقه را در 60 دقیقه آخر داده رویداد درخواست کنند ( endMinutesAgo <= 59 ). |
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-01-05 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-01-05 بهوقت ساعت هماهنگ جهانی."],[[["Retrieves customized, realtime event data for your Google Analytics 4 property, displaying events seconds after they are sent."],["Realtime reports cover data from the present moment to 30 minutes ago (up to 60 minutes for Google Analytics 360 properties)."],["The API allows filtering and ordering of data, aggregation of metrics, and limiting the number of rows returned."],["You can request data for specific minute ranges within the allowed timeframe, with up to 2 minute ranges per request."],["Requires authorization with specific OAuth scopes for read-only or full access to Google Analytics data."]]],["This document outlines how to request and receive realtime event data reports from Google Analytics. The core actions involve sending a `POST` request to the specified endpoint with a property identifier in the URL. The request body defines the report's dimensions, metrics, filters, row limits, metric aggregations, ordering, quota options, and minute ranges. The response includes dimension and metric headers, rows of data, totals, minimums, maximums, row count, property quota, and a response kind identifier. The available minute ranges are up to 30 minutes ago for standard and 60 minutes ago for 360 properties.\n"]]