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)

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

אופציונלי. ההגדרה של ההשוואות המבוקשות והמוצגות. כדי לקבל עמודת השוואה בתשובה, צריך לכלול בבקשה רק שדה השוואות.
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,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "dimensionFilter": {
    object (FilterExpression)
  },
  "comparison": string
  // End of mutually exclusive fields.
}
שדות
name

string

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