Google Analytics Data API v1 מאפשר ליצור טבלאות צירים. מגביה כידון Pivot טבלאות הן כלי לסיכום נתונים שממחיש באופן חזותי את הנתונים על ידי סידור מחדש של הנתונים בטבלה על ידי הצגת הנתונים בסבב (סבב) מאפיינים.
כדוגמה, נבחן את טבלת הנתונים הגולמיים הבאה:
בעזרת הנתונים האלה ניתן ליצור טבלת צירים ולפרט נתוני סשנים לפי דפדפן, כאשר מאפייני המדינה והשפה נבחרו בתור משתנים נוספים.
תכונות משותפות עם דוחות ליבה
הסמנטיקה של בקשות לדיווח על צירים זהה לזו של בקשות לדוח הליבה עבור בהרבה תכונות משותפות. לדוגמה, עימוד, מסנני מאפיינים ומשתמש מאפיינים פועלים באותו אופן בדוחות צירים כמו בדוחות ליבה. הזה שמתמקד בתכונות דיווח בטבלת צירים. ללמוד להכיר את תוכנית הליבה פונקציונליות הדיווח של Data API v1. אפשר לקרוא את המדריך הבסיסי לדיווח. וגם במדריך תרחישים מתקדמים לדוגמה.
שיטות דיווח על צירים
Data API v1 תומך בפונקציונליות של צירים בשיטות הדיווח הבאות:
runPivotReport בשיטה הזו מחזירה דוח צירים בהתאמה אישית של נתוני האירוע ב-Google Analytics. כל אחד בצירופים מתוארים העמודות והשורות של המאפיינים הגלויים בתגובת הדוח.
batchRunPivotReports היא גרסת אצווה של ה-method
runPivotReportשמאפשרת ליצור דוחות מרובים באמצעות קריאה אחת ל-API.
בחירת ישות מדווחת
לכל השיטות ב-Data API v1 נדרש מזהה הנכס של Google Analytics
יצוין בתוך נתיב בקשה של כתובת URL,
properties/GA_PROPERTY_ID, למשל:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
הדוח יופק על סמך נתוני האירוע ב-Google Analytics שנאספו בנכס Google Analytics שצוין.
אם אתם משתמשים באחת מספריות הלקוח של Data API,
אין צורך לשנות באופן ידני את נתיב כתובת ה-URL של הבקשה. רוב לקוחות API
מספקים פרמטר property שמצפה למחרוזת בצורת
properties/GA_PROPERTY_ID. לעיון במדריך למתחילים
כדי לקבל דוגמאות לשימוש בספריות הלקוח.
בקשה לדוח צירים
כדי ליצור בקשה באמצעות טבלת צירים, צריך להשתמש באחת מהאפשרויות הבאות: runPivotReport או batchRunPivotReports .
כדי לבקש נתונים בתצוגת צירים, אפשר ליצור RunPivotReportRequest לאובייקט. מומלץ להתחיל עם הפרמטרים הבאים של הבקשות:
- ערך חוקי בשדה dateRanges.
- לפחות ערך חוקי אחד בשדה מאפיינים
- לפחות ערך חוקי אחד בשדה מדדים.
- לפחות שתי רשומות חוקיות של ציר בשדה pivots.
הנה בקשה לדוגמה עם השדות המומלצים:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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 מתאר את המאפיין הגלוי
העמודות והשורות בתגובת הדוח.
Data API v1 תומך במספר צירים כל עוד המכפלה של המגבלה לכל ציר לא עולה על 100,000.
בהמשך מופיע קטע קוד שמדגים את השימוש ב-pivots ליצירת דוח של
ספירות סשנים לפי מדינה, בטבלת צירים לפי המאפיין browser. שימו לב איך
השאילתה משתמשת בשדה orderBys עבור
מיון, והמגבלה
שדות קיזוז כדי להטמיע חלוקה לדפים.
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
...
מידות
מאפיינים מתארים ומקבצים נתוני אירועים עבור
באתר או באפליקציה. לדוגמה, המאפיין city מציין את העיר ("פריז"
או 'תל אביב') שממנו הגיע כל אירוע. בבקשת הדיווח, אפשר
לציין אפס מאפיינים או יותר.
יש להגדיר את המידות בתוך
מאפיינים
בשדה בגוף הבקשה. כדי שהמאפיינים האלה יוצגו בדוח, הם צריכים גם
רשומים ב-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 מופיעה במדדי ה-API. שאפשר לציין אותן בבקשות.
בבקשות לדוחות צירים, המדדים מוגדרים באמצעות השדה metrics,
גוף הבקשה, שדומה לשיטות דיווח ליבה.
הדוגמה הבאה מציינת את מספר הסשנים שישמשו כערך מדד דוח:
"metrics": [
{
"name": "sessions"
}
],
צבירת מדדים
משתמשים בmetricAggregations של אובייקט ציר לחישוב מדד מצטבר בכל ציר.
צבירת הנתונים יחושבו רק אם metricAggregations השדה מצוין בבקשה.
בהמשך מופיע קטע של שאילתה שמבקשת את הסכומים הכוללים עבור
מאפיין ציר browser:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
המדדים המחושבים מוחזרים בקטע צבירת נתונים
השדה 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"
}
]
},
....
}
חלוקה לדפים
בדומה לשיטות דיווח ליבה, בקשות צירים מאפשרות לך
כדי לציין את המגבלה
ו-offset משדות
אובייקט Pivot כדי להטמיע עימוד.
הגדרות העימוד חלות על כל ציר בנפרד.
השדה limit חובה לכל אובייקט Pivot כדי להגביל את
של העוצמה (cardinality).
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"
}
]
},
...
]
הנתונים האלה תואמים לשני התאים שמודגשים בטבלה הבאה:
ספריות לקוח
ניתן למצוא הסבר במדריך למתחילים איך להתקין ולהגדיר ספריות לקוח.
בדוגמאות הבאות נעשה שימוש בספריית הלקוח כדי להריץ שאילתת ציר כדי ליצור דוח של ספירת הסשנים לפי מדינה, בציר לפי מאפיין הדפדפן.
PHP
use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient;
use Google\Analytics\Data\V1beta\DateRange;
use Google\Analytics\Data\V1beta\Dimension;
use Google\Analytics\Data\V1beta\Metric;
use Google\Analytics\Data\V1beta\OrderBy;
use Google\Analytics\Data\V1beta\OrderBy\DimensionOrderBy;
use Google\Analytics\Data\V1beta\OrderBy\MetricOrderBy;
use Google\Analytics\Data\V1beta\Pivot;
use Google\Analytics\Data\V1beta\RunPivotReportRequest;
use Google\Analytics\Data\V1beta\RunPivotReportResponse;
/**
* Runs a pivot query to build a report of session counts by country,
* pivoted by the browser dimension.
* @param string $propertyId Your GA-4 Property ID
*/
function run_pivot_report(string $propertyId)
{
// Create an instance of the Google Analytics Data API client library.
$client = new BetaAnalyticsDataClient();
// Make an API call.
$request = (new RunPivotReportRequest())
->setProperty('properties/' . $propertyId)
->setDateRanges([new DateRange([
'start_date' => '2021-01-01',
'end_date' => '2021-01-30',
]),
])
->setPivots([
new Pivot([
'field_names' => ['country'],
'limit' => 250,
'order_bys' => [new OrderBy([
'dimension' => new DimensionOrderBy([
'dimension_name' => 'country',
]),
])],
]),
new Pivot([
'field_names' => ['browser'],
'offset' => 3,
'limit' => 3,
'order_bys' => [new OrderBy([
'metric' => new MetricOrderBy([
'metric_name' => 'sessions',
]),
'desc' => true,
])],
]),
])
->setMetrics([new Metric(['name' => 'sessions'])])
->setDimensions([
new Dimension(['name' => 'country']),
new Dimension(['name' => 'browser']),
]);
$response = $client->runPivotReport($request);
printPivotReportResponse($response);
}
/**
* Print results of a runPivotReport call.
* @param RunPivotReportResponse $response
*/
function printPivotReportResponse(RunPivotReportResponse $response)
{
print 'Report result: ' . PHP_EOL;
foreach ($response->getRows() as $row) {
printf(
'%s %s' . PHP_EOL,
$row->getDimensionValues()[0]->getValue(),
$row->getMetricValues()[0]->getValue()
);
}
}
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)
Node.js
// TODO(developer): Uncomment this variable and replace with your
// Google Analytics 4 property ID before running the sample.
// propertyId = 'YOUR-GA4-PROPERTY-ID';
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Initialize client that will be used to send requests. This client only
// needs to be created once, and can be reused for multiple requests.
const analyticsDataClient = new BetaAnalyticsDataClient();
// Runs a pivot query to build a report of session counts by country, pivoted by the browser dimension.
async function runPivotReport() {
const [response] = await analyticsDataClient.runPivotReport({
property: `properties/${propertyId}`,
dateRanges: [
{
startDate: '2021-01-01',
endDate: '2021-01-30',
},
],
pivots: [
{
fieldNames: ['country'],
limit: 250,
orderBys: [
{
dimension: {
dimensionName: 'country',
},
},
],
},
{
fieldNames: ['browser'],
offset: 3,
limit: 3,
orderBys: [
{
metric: {
metricName: 'sessions',
},
desc: true,
},
],
},
],
metrics: [
{
name: 'sessions',
},
],
dimensions: [
{
name: 'country',
},
{
name: 'browser',
},
],
});
printPivotReportResponse(response);
}
runPivotReport();
// Prints results of a runReport call.
function printPivotReportResponse(response) {
console.log('Report result:');
response.rows.forEach(row => {
row.dimensionValues.forEach(dimensionValue => {
console.log(dimensionValue.value);
});
row.metricValues.forEach(metricValue => {
console.log(metricValue.value);
});
});
}
בקשה להדגמה (דמו)
לצפייה בהדגמה של דוח הצירים של Google Analytics API v1 אפליקציה דוגמה לאופן שבו אפשר לבנות ולהציג דוח צירים באמצעות JavaScript.