Method: properties.runReport

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

בקשת HTTP

POST https://analyticsdata.googleapis.com/v1alpha/{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)
    }
  ],
  "conversionSpec": {
    object (ConversionSpec)
  }
}
שדות
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)

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

object (ConversionSpec)

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

גוף התשובה

טבלת דוח התגובות שמתאימה לבקשה.

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

ייצוג JSON 
{
  "dimensionHeaders": [
    {
      object (DimensionHeader)
    }
  ],
  "metricHeaders": [
    {
      object (MetricHeader)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "totals": [
    {
      object (Row)
    }
  ],
  "maximums": [
    {
      object (Row)
    }
  ],
  "minimums": [
    {
      object (Row)
    }
  ],
  "rowCount": integer,
  "metadata": {
    object (ResponseMetaData)
  },
  "propertyQuota": {
    object (PropertyQuota)
  },
  "kind": string,
  "nextPageToken": string
}
שדות
dimensionHeaders[]

object (DimensionHeader)

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

object (MetricHeader)

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

object (Row)

שורות של שילובים של ערכי מאפיינים וערכי מדדים בדוח.
totals[]

object (Row)

אם מתבקש, הערכים הכוללים של המדדים.
maximums[]

object (Row)

אם נדרש, הערכים המקסימליים של המדדים.
minimums[]

object (Row)

אם נדרש, הערכים המינימליים של המדדים.
rowCount

integer

המספר הכולל של השורות בתוצאת השאילתה, ללא קשר למספר השורות שמוחזרות בתגובה. לדוגמה, אם שאילתה מחזירה 175 שורות וכוללת את הערך limit = 50 בבקשת ה-API, התגובה תכיל את הערך rowCount = 175 אבל רק 50 שורות.

מידע נוסף על הפרמטר הזה של מעבר עמוד זמין במאמר בנושא מעבר עמוד.
metadata

object (ResponseMetaData)

מטא-נתונים של הדוח.
propertyQuota

object (PropertyQuota)

מצב המכסה של נכס Analytics הזה, כולל הבקשה הזו.
kind

string

מזהה את סוג המשאב של ההודעה. הערך kind הוא תמיד המחרוזת הקבועה analyticsData#runReport. הפרמטר הזה שימושי להבחנה בין סוגי תגובות ב-JSON.
nextPageToken

string

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

היקפי הרשאות

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

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

השוואה

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

ייצוג JSON 
{
  "name": string,

  // Union field one_comparison can be only one of the following:
  "dimensionFilter": {
    object (FilterExpression)
  },
  "comparison": string
  // End of list of possible types for union field one_comparison.
}
שדות
name

string

כל השוואה יוצרת שורות נפרדות בתגובה. בתגובה, ההשוואה הזו מזוהה לפי השם הזה. אם לא מציינים שם, נשתמש בשם לתצוגה של ההשוואות שנשמר.

שדה איחוד one_comparison.

הערך one_comparison יכול להיות רק אחד מהבאים:
dimensionFilter

object (FilterExpression)

השוואה בסיסית.
comparison

string

השוואה שנשמרה, שמזוהה לפי שם המשאב של ההשוואה. לדוגמה, 'comparisons/1234'.

ConversionSpec

שולט בדיווח על המרות.

ייצוג JSON 
{
  "conversionActions": [
    string
  ],
  "attributionModel": enum (AttributionModel)
}
שדות
conversionActions[]

string

מזהי פעולות ההמרה שייכללו בדוח. אם השדה ריק, כל ההמרות נכללות. אפשר לאחזר מזהים תקינים של פעולות המרה מהשדה conversionAction ברשימה conversions בתשובה של השיטה properties.getMetadata. לדוגמה, 'conversionActions/1234'.
attributionModel

enum (AttributionModel)

מודל השיוך שבו רוצים להשתמש בדוח ההמרות. אם לא מציינים ערך, המערכת משתמשת ב-DATA_DRIVEN.

AttributionModel

מודל השיוך (Attribution) לשימוש בדוח ההמרות

טיפוסים בני מנייה (enum)
ATTRIBUTION_MODEL_UNSPECIFIED מודל שיוך (Attribution) לא צוין.
DATA_DRIVEN השיוך התבסס על מודל מבוסס נתונים מהחיפוש האורגני ונתונים בתשלום
LAST_CLICK השיוך התבסס על מודל הקליק האחרון בערוצים בתשלום ובערוצים אורגניים