Method: properties.runRealtimeReport

הפונקציה מחזירה דוח בהתאמה אישית של נתוני אירועים בזמן אמת לגבי הנכס שלכם. אירועים מופיעים בדוחות בזמן אמת שניות אחרי שהם נשלחו אל Google Analytics. בדוחות 'זמן אמת' מוצגים אירועים ונתוני שימוש לפרקי זמן, החל מהרגע הנוכחי ועד לפני 30 דקות (עד 60 דקות בנכסי Google Analytics 360).

מדריך ליצירת בקשות בזמן אמת והבנת התגובות זמין במאמר יצירת דוח 'זמן אמת'.

בקשת HTTP

POST https://analyticsdata.googleapis.com/v1beta/{property=properties/*}:runRealtimeReport

בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.

פרמטרים של נתיב

פרמטרים
property

string

מזהה נכס GA4 של Google Analytics שיש מעקב אחרי האירועים שלו. מצוין בנתיב כתובת ה-URL ולא בגוף הטקסט. למידע נוסף, אפשר לעיין במאמר איפה למצוא את מזהה הנכס.

דוגמה: properties/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)

סעיף הסינון של המדדים. היא מיושמת בשלב של צבירה לאחר צבירה (post aggregation), בדומה לתרחיש לדוגמה של SQL. אי אפשר להשתמש במימדים במסנן הזה.
limit

string (int64 format)

מספר השורות שיש להחזיר. אם לא צוין אחרת, יוחזרו 10,000 שורות. ה-API מחזיר עד 250,000 שורות לבקשה, ללא קשר לכמות שתבקש. הערך limit חייב להיות חיובי.

כמו כן, ה-API יכול להחזיר פחות שורות מהשדה limit המבוקש, אם אין מספיק ערכי מאפיינים כמו המאפיין limit. לדוגמה, יש פחות מ-300 ערכים אפשריים למאפיין 'country', כך שכשמדווחים רק על country, אי אפשר לקבל יותר מ-300 שורות, גם אם מגדירים ל-limit ערך גבוה יותר.
metricAggregations[]

enum (MetricAggregation)

צבירת מדדים. ערכי המדדים הנצברים יוצגו בשורות שבהן ערכי ה-dimensionValue מוגדרים כ-"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)

מתאר את עמודות המימדים. מספר הכותרות של מימדים והסדר של 'כותרות המאפיינים' תואם למאפיינים שמוצגים בשורות.
metricHeaders[]

object (MetricHeader)

מתאר עמודות מטריות. מספר הכותרות של MetricHeaders והסדר של 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#runRTTReport". שימושי להבחנה בין סוגי תגובות ב-JSON.

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/analytics.readonly
  • https://www.googleapis.com/auth/analytics

MinuteRange

קבוצת דקות רציפה: 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), ונכסי Analytics 360 יכולים לבקש נתוני אירועים של עד 60 הדקות האחרונות (startMinutesAgo <= 59).
endMinutesAgo

integer

דקת הסיום הכוללת של השאילתה כמספר דקות לפני כן. לא יכול להיות לפני startMinutesAgo. לדוגמה, "endMinutesAgo": 15 מציין שהדוח צריך לכלול נתוני אירועים שהתרחשו לפני 15 דקות.

אם לא צוין הערך, ברירת המחדל של endMinutesAgo היא 0. נכסי Analytics רגילים יכולים לבקש נתוני אירועים מכל דקה ב-30 הדקות האחרונות (endMinutesAgo <= 29), ונכסי Analytics 360 יכולים לבקש נתוני אירועים מכל דקה ב-60 הדקות האחרונות (endMinutesAgo <= 59).