Google Analytics Data API v1 מאפשר ליצור טבלאות צירים. טבלאות צירים הן כלי לסיכום נתונים שמציג נתונים על ידי סידור מחדש של המידע בטבלה על ידי סיבוב (סיבוב) הנתונים לפי מאפיין אחד או יותר.
כדוגמה, נשתמש בטבלת הנתונים הגולמיים הבאה:
על סמך הנתונים האלו ניתן ליצור טבלת צירים ולפלח את נתוני הסשנים לפי דפדפן, ולבחור במאפיינים של מדינה ושפה כצירים נוספים.
תכונות משותפות עם דוחות ליבה
הסמנטיקה של בקשות לדיווח על צירים היא זהה לבקשות של דוחות ליבה בהרבה תכונות משותפות. לדוגמה, חלוקה לדפים, מסנני מאפיינים ומאפייני משתמשים מתנהגים באותו אופן בדוחות צירים כמו דוחות ליבה. מדריך זה מתמקד בתכונות של דיווח על צירים. כדי להכיר את פונקציונליות הדיווח העיקרית של Data API v1, קראו את המדריך הבסיסי לדיווח וגם תרחישים מתקדמים לשימוש.
שיטות דיווח על צירים
Data API v1 תומך בפונקציונליות צירים בשיטות הדיווח הבאות:
runPivotReport: השיטה הזו מחזירה דוח ציר מותאם אישית של נתוני האירועים ב-Google Analytics. כל ציר מתאר את השורות והעמודות של המאפיינים הגלויים בתגובה לדוח.
batchRunPivotReports זוהי גרסת אצווה של השיטה
runPivotReportשמאפשרת ליצור מספר דוחות באמצעות קריאה אחת ל-API.
בחירת ישות מדווחת
בכל השיטות של Data API v1 צריך לציין את מזהה נכס Google Analytics 4 בתוך נתיב הבקשה לכתובת URL, בפורמט properties/GA4_PROPERTY_ID. לדוגמה:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
הדוח שמתקבל יווצר על סמך נתוני האירועים ב-Google Analytics שנאספו בנכס Google Analytics 4 שצוין.
אם אתם משתמשים באחת מספריות הלקוח של Data API, אין צורך לשנות את נתיב כתובת ה-URL של הבקשה באופן ידני. רוב לקוחות ה-API מספקים פרמטר property, שמצפה למחרוזת בפורמט properties/GA4_PROPERTY_ID. במדריך למתחילים מוצגות דוגמאות לשימוש בספריות הלקוח.
בקשת דוח ציר
כדי ליצור בקשה באמצעות טבלת צירים, משתמשים בשיטה runPivotReport או בשיטה batchRunPivotReports.
כדי לבקש נתונים שמוצגים בצירים, אפשר ליצור אובייקט RunPivotReportRequest. מומלץ להתחיל עם הפרמטרים הבאים של הבקשה:
- רשומה חוקית בשדה dateRanges.
- לפחות רשומה חוקית אחת בשדה מאפיינים.
- לפחות רשומה חוקית אחת בשדה metrics.
- לפחות שתי רשומות צירים חוקיות בשדה pivots.
לפניכם בקשה לדוגמה עם השדות המומלצים:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [
{ "name": "browser" },
{ "name": "country" },
{ "name": "language" }
],
"metrics": [{ "name": "sessions" }],
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5
},
{
"fieldNames": [
"country"
],
"limit": 250
},
{
"fieldNames": [
"language"
],
"limit": 15
}
]
}
צירים
כדי להגדיר צירים בדוח, משתמשים באובייקטים Pivot בשדה pivot של גוף הבקשה. כל Pivot מתאר את העמודות והשורות של המאפיינים הגלויים בתגובה לדוח.
ב-Data API v1 יש תמיכה במספר צירים, כל עוד המכפלה של הפרמטר limit בכל צירים לא עולה על 100,000.
בהמשך מופיע קטע שמדגים את השימוש ב-pivots כדי ליצור דוח של ספירת סשנים לפי מדינה, כשהוא מוצג בציר לפי המאפיין browser. שימו לב איך השאילתה משתמשת בשדה orderBys למיון, ובשדות limit והיסט כדי להטמיע עימוד.
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
...
מאפיינים
מאפיינים מתארים ומקבצים נתוני אירועים עבור האתר או האפליקציה. לדוגמה, המאפיין city מציין את העיר ("פריז" או "ניו יורק") שממנה הגיע כל אירוע. בבקשת דוח, ניתן לך לציין אפס מאפיינים או יותר.
המאפיינים חייבים להיות מוגדרים בשדה dimensions של גוף הבקשה. כדי שהמאפיינים האלה יופיעו בדוח, הם צריכים להיות רשומים גם בשדה fieldNames באובייקט Pivot.
מאפיין מסוים לא יוצג בדוח אם לא משתמשים בו בשום ציר בשאילתת צירים. לא כל מאפיין חייב להיכלל ב-fieldNames של הצירים. ניתן להשתמש במאפיינים רק במסננים, ולא בתוך fieldNames בכל צירים.
בהמשך מופיע קטע קוד שמדגים את השימוש בשדות dimension ו-fieldNames בטבלה עם צירים browser, country ו-language:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
},
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"language"
],
"limit": 10
}
],
מדדים
מדדים הם מדידות כמותיות של נתוני אירועים באתר או באפליקציה. בבקשת דוח, ניתן לציין מדד אחד או יותר. ב-API Metrics מופיעה רשימה מלאה של השמות של מדדי ה-API שזמינים לציון בבקשות.
בבקשות לדוח צירים, המדדים מוגדרים באמצעות השדה metrics בגוף הבקשה, בדומה לשיטות דיווח ליבה.
דוגמה למטה מציינת את ספירת הסשנים שישמשו כערך מדד בדוח:
"metrics": [
{
"name": "sessions"
}
],
צבירת מדדים
משתמשים בשדה metricAggregations באובייקט Pivot כדי לחשב ערכי מדדים מצטברים לכל ציר.
נתוני הצבירה יחושבו רק אם השדה metricAggregations צוין בבקשה.
בהמשך מופיע קטע של שאילתה שמבקשת את הסכומים הכוללים של מאפיין הצירים browser:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
המדדים המחושבים מוחזרים בשדה aggregates של האובייקט RunPivotReportResponse. בשורות של מדדים נצברים, השדה dimensionValues מכיל ערך מיוחד של RESERVED_TOTAL, RESERVED_MAX או RESERVED_MIN.
"aggregates": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6"
}
]
},
....
}
חלוקה לדפים
בדומה לשיטות דיווח ליבה, בקשות צירים מאפשרות לציין את השדות limit וoffset באובייקט Pivot כדי להטמיע עימוד.
הגדרות העימוד חלות על כל ציר בנפרד.
השדה limit נדרש לכל אובייקט Pivot כדי להגביל את העוצמה של הדוח.
ב-Data API v1 יש תמיכה במספר צירים, כל עוד המכפלה של הפרמטר limit בכל צירים לא עולה על 100,000.
בהמשך מופיע קטע קוד שמדגים את השימוש בשדות offset ו-limit כדי לאחזר את חמשת המאפיינים הבאים של language עם היסט של 10:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
סינון
בדומה לפונקציונליות של דיווח מרכזי, חובה להשתמש במסנן מאפיינים ברמת הבקשה אם רוצים לסנן מאפיינים בבקשת דיווח על צירים.
מיון
אפשר לשלוט בהתנהגות הסדר של שאילתות של דוח צירים בנפרד לכל ציר בנפרד, באמצעות השדה orderBys של אובייקט Pivot, שמכיל רשימה של אובייקטים מסוג OrderBy.
כל OrderBy יכול להכיל אחד מהבאים:
- השדה DimensionOrderBy ממיין את התוצאות לפי ערכי המאפיין.
- MetricOrderBy, מיון התוצאות לפי הערכים של המדד.
- PivotOrderBy, משמש בשאילתות ציר ומיון התוצאות לפי ערכי המדד בקבוצה של עמודות צירים.
בדוגמה הזו מוצג קטע קוד להגדרת ציר, שמסדר את הדוח לפי המאפיין browser ומסדר את התוצאות לפי המדד sessions בסדר יורד.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
דיווח על תגובה
תגובת דוח ציר של בקשת API לדוח צירים היא בעיקר כותרת ושורות.
כותרות תגובה
הכותרת של דוח הצירים כוללת את PivotHeaders, DimensionHeaders ו-MetricHeaders שבהם מפורטות העמודות בדוח הצירים.
לדוגמה, דוח עם מאפייני הצירים browser, country ו-language והמדד sessions יניב כותרות כאלה:
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Chrome"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "United States"
}
]
},
{
"dimensionValues": [
{
"value": "Canada"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "English"
}
]
},
{
"dimensionValues": [
{
"value": "French"
}
]
},
...
],
...
}
],
"dimensionHeaders": [
{
"name": "browser"
},
{
"name": "country"
},
{
"name": "language"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
...
}
התרשים הבא ממחיש את התפקיד של כל רכיב בדוח הצירים תגובה לעיבוד דוח הצירים:
שורות תשובה
התגובה של דוח הצירים של השיטות runPivotReport ו-batchRunPivotReports שונה מהתגובה לשיטות דיווח מרכזיות כמו runReport ו-batchRunReports כי כל שורת תגובה של דוח צירים מייצגת תא יחיד בטבלה, ואילו בדוח רגיל, שורת תגובה יחידה מייצגת שורה שלמה בטבלה.
בהמשך מופיע מקטע של תגובה לדוח צירים עבור שאילתה עם מאפייני הצירים browser, country ו-language ועם המדד sessions. כל תא בדוח הצירים מוחזר בנפרד:
"rows": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "United States"
},
{
"value": "English"
}
],
"metricValues": [
{
"value": "1"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "Canada"
},
{
"value": "French"
}
],
"metricValues": [
{
"value": "3"
}
]
},
...
]
הנתונים תואמים לשני התאים המודגשים בטבלה הבאה:
ספריות לקוח
במדריך למתחילים מוסבר איך להתקין ולהגדיר ספריות לקוח.
בהמשך מוצגת דוגמה לשימוש בספריית הלקוח של Python שמריצה שאילתת ציר כדי ליצור דוח של ספירת סשנים לפי מדינה, בחלוקה לפי מאפיין הדפדפן.
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
DateRange,
Dimension,
Metric,
OrderBy,
Pivot,
RunPivotReportRequest,
)
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
run_pivot_report(property_id)
def run_pivot_report(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a pivot query to build a report of session counts by country,
pivoted by the browser dimension."""
client = BetaAnalyticsDataClient()
request = RunPivotReportRequest(
property=f"properties/{property_id}",
date_ranges=[DateRange(start_date="2021-01-01", end_date="2021-01-30")],
pivots=[
Pivot(
field_names=["country"],
limit=250,
order_bys=[
OrderBy(
dimension=OrderBy.DimensionOrderBy(dimension_name="country")
)
],
),
Pivot(
field_names=["browser"],
offset=3,
limit=3,
order_bys=[
OrderBy(
metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True
)
],
),
],
metrics=[Metric(name="sessions")],
dimensions=[Dimension(name="country"), Dimension(name="browser")],
)
response = client.run_pivot_report(request)
print_run_pivot_report_response(response)
def print_run_pivot_report_response(response):
"""Prints results of a runPivotReport call."""
print("Report result:")
for row in response.rows:
for dimension_value in row.dimension_values:
print(dimension_value.value)
for metric_value in row.metric_values:
print(metric_value.value)
בקשה להדגמה (דמו)
אפשר לעיין באפליקציית Google Analytics API v1 Pivot Report כדי לראות דוגמה ליצירה ולהצגה של דוח ציר באמצעות JavaScript.