Method: properties.batchRunReports

הפונקציה מחזירה דוחות מרובים בבת אחת. כל הדוחות חייבים להיות משויכים לאותו נכס GA4.

בקשת HTTP

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

בכתובת ה-URL נעשה שימוש בתחביר המרת gRPC.

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

פרמטרים
property

string

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

דוגמה: properties/1234

גוף הבקשה

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

ייצוג JSON
{
  "requests": [
    {
      object (RunReportRequest)
    }
  ]
}
שדות
requests[]

object (RunReportRequest)

בקשות נפרדות. לכל בקשה יש הודעת דוח נפרדת. כל בקשה באצווה יכולה לכלול עד 5 בקשות.

גוף התשובה

תגובה באצווה שמכילה כמה דוחות.

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

ייצוג JSON
{
  "reports": [
    {
      object (RunReportResponse)
    }
  ],
  "kind": string
}
שדות
reports[]

object (RunReportResponse)

תשובות בודדות. לכל תגובה יש בקשת דוח נפרדת.

kind

string

מזהה את סוג המשאב שההודעה הזו מוצגת. kind הוא תמיד המחרוזת הקבועה "analyticsData#batchRunReports". שימושי להבחנה בין סוגי תגובות ב-JSON.

היקפי הרשאות

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

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

RunReportRequest

הבקשה ליצירת דוח.

ייצוג JSON
{
  "property": string,
  "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
}
שדות
property

string

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

דוגמה: properties/1234

dimensions[]

object (Dimension)

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

metrics[]

object (Metric)

המדדים המבוקשים ומוצגים.

dateRanges[]

object (DateRange)

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

dimensionFilter

object (FilterExpression)

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

metricFilter

object (FilterExpression)

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

צבירת מדדים. ערכי המדדים המצטברים יוצגו בשורות שבהן ערכי ה-dimensionValue מוגדרים כ-"RESERVED_(MetricAggregation)".

orderBys[]

object (OrderBy)

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

currencyCode

string

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

cohortSpec

object (CohortSpec)

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

keepEmptyRows

boolean

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

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

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

returnPropertyQuota

boolean

לחצן החלפת מצב כדי לבחור אם להחזיר את המצב הנוכחי של המכסה בנכס Analytics הזה. המכסות מוחזרות ב-PropertyQuota.