Method: properties.runRealtimeReport

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

במאמר יצירת דוח בזמן אמת מוסבר איך יוצרים בקשות בזמן אמת ומפרטים את התשובות.

בקשת HTTP

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

כתובת ה-URL משתמשת בתחביר של Transcoding של gRPC.

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

פרמטרים
property

string

מזהה של נכס 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)

תנאי הסינון של המדדים. חל בשלב שלאחר הצבירה, בדומה לתנאי having ב-SQL. אי אפשר להשתמש במאפיינים במסנן הזה.
limit

string (int64 format)

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

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

enum (MetricAggregation)

צבירת מדדים. ערכי המדדים המצטברים יוצגו בשורות שבהן הערך של dimensionValues מוגדר כ-'RESERVED_(MetricAggregation)'.
orderBys[]

object (OrderBy)

מציין את סדר השורות בתגובה.
returnPropertyQuota

boolean

מצב שמציין אם להחזיר את המצב הנוכחי של המכסה בזמן אמת של נכס Google Analytics הזה. המכסה מוחזר ב-PropertyQuota.
minuteRanges[]

object (MinuteRange)

טווחי הדקות של נתוני האירועים לקריאה. אם לא צוין טווח, המערכת תשתמש בטווח של דקה אחת ב-30 הדקות האחרונות. אם מבקשים כמה טווחי דקות, כל שורת תגובה תכיל אינדקס של טווח דקות שמתחיל ב-0. אם שני טווחי דקות חופפים, נתוני האירועים של הדקות החופפות נכללים בשורות התגובה של שני טווחי הדקות.

גוף התשובה

טבלת הדוח של התשובה בזמן אמת שתואם לבקשה.

אם הפעולה מצליחה, גוף התגובה מכיל נתונים במבנה הבא:

ייצוג ב-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)

תיאור של עמודות מאפיינים. מספר ה-DimensionHeaders והסדר שלהם תואמים למאפיינים שקיימים בשורות.
metricHeaders[]

object (MetricHeader)

תיאור של עמודות מדדים. מספר הכותרות של המדדים והסדר שלהן תואמים למדדים שמופיעים בשורות.
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)

מצב המכסה בזמן אמת של הנכס הזה ב-Google Analytics, כולל הבקשה הזו.
kind

string

מזהה את סוג המשאב של ההודעה הזו. הערך של kind הוא תמיד המחרוזת הקבועה analyticsData#runRealtimeReport. שימושי להבדיל בין סוגי התשובות ב-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).