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

درخواست بدن

بدنه درخواست حاوی داده هایی با ساختار زیر است:

نمایندگی JSON
{
  "dimensions": [
    {
      object (Dimension)
    }
  ],
  "metrics": [
    {
      object (Metric)
    }
  ],
  "dimensionFilter": {
    object (FilterExpression)
  },
  "metricFilter": {
    object (FilterExpression)
  },
  "limit": string,
  "metricAggregations": [
    enum (MetricAggregation)
  ],
  "orderBys": [
    {
      object (OrderBy)
    }
  ],
  "returnPropertyQuota": boolean,
  "minuteRanges": [
    {
      object (MinuteRange)
    }
  ]
}
زمینه های
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 ).