Method: properties.runReport

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

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

בקשת HTTP

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

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

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

פרמטרים
property

string

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

דוגמה: properties/1234

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "dimensions": [
    {
      object (Dimension)
    }
  ],
  "metrics": [
    {
      object (Metric)
    }
  ],
  "dateRanges": [
    {
      object (DateRange)
    }
  ],
  "dimensionFilter": {
    object (FilterExpression)
  },
  "metricFilter": {
    object (FilterExpression)
  },
  "offset": string,
  "limit": string,
  "metricAggregations": [
    enum (MetricAggregation)
  ],
  "orderBys": [
    {
      object (OrderBy)
    }
  ],
  "currencyCode": string,
  "cohortSpec": {
    object (CohortSpec)
  },
  "keepEmptyRows": boolean,
  "returnPropertyQuota": boolean,
  "comparisons": [
    {
      object (Comparison)
    }
  ]
}
שדות
dimensions[]

object (Dimension)

המאפיינים המבוקשים והמוצגים.
metrics[]

object (Metric)

המדדים שנשלחו ובוצעה עבורם בקשה להצגה.
dateRanges[]

object (DateRange)

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

object (FilterExpression)

מסנני מאפיינים מאפשרים לבקש רק ערכי מאפיינים ספציפיים בדוח. למידע נוסף ולדוגמאות, אפשר לעיין במאמר יסודות של מסנני מאפיינים. לא ניתן להשתמש במדדים במסנן הזה.
metricFilter

object (FilterExpression)

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

string (int64 format)

מספר השורות של שורת ההתחלה. השורה הראשונה נספרת כשורה 0.

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

מידע נוסף על הפרמטר הזה של חלוקה לדפים זמין במאמר חלוקה לדפים.
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)

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

string

קוד מטבע בפורמט ISO4217, למשל 'AED',‏ 'USD',‏ 'JPY'. אם השדה ריק, המערכת תשתמש במטבע ברירת המחדל של הנכס בדוח.
cohortSpec

object (CohortSpec)

קבוצת 'קבוצה בעלת מאפיינים משותפים' שמשויכת לבקשה הזו. אם יש בבקשה קבוצת 'קבוצה בעלת מאפיינים משותפים', צריך לכלול את המאפיין 'קבוצה בעלת מאפיינים משותפים'.
keepEmptyRows

boolean

אם הערך הוא false או לא צוין, לא תוחזר כל שורה שבה כל המדדים שווים ל-0. אם הערך הוא true, השורות האלה יחזרו אם הן לא יוסרו בנפרד על ידי מסנן.

ללא קשר להגדרה keepEmptyRows, רק נתונים שתועדו בנכס Google Analytics יוצגו בדוח.

לדוגמה, אם בנכס אף פעם לא מתועד אירוע purchase, בשאילתה למאפיין eventName ולמדד eventCount לא תופיע השורה eventName:‏ "purchase" ו-eventCount: ‏ 0.
returnPropertyQuota

boolean

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

object (Comparison)

זה שינוי אופציונלי. ההגדרה של ההשוואות המבוקשות והמוצגות. כדי לקבל עמודה של השוואה בתגובה, צריך רק להוסיף שדה השוואות לבקשה.

גוף התשובה

אם הפעולה מצליחה, גוף התגובה מכיל מופע של RunReportResponse.

היקפי הרשאה

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

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