Method: properties.runReport

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

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

בקשת HTTP

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

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

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

פרמטרים
property

string

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

דוגמה: 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.

כשמבצעים החלפה בין דפים, הבקשה הראשונה לא מציינת היסט, או שהיא מגדירה את ההיסט ל-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)

קבוצת הקוהורט שמשויכת לבקשה הזו. אם יש בקשה לקבוצה בעלת מאפיינים משותפים, המימד cohort חייב להיות נוכח.
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