במסמך זה נסביר איך להעביר את הקוד הקיים מ-Google Analytics Reporting API v4 אל Google Analytics Data API v1, ונותנת סקירה כללית קצרה על ההבדלים העיקריים בין שני ממשקי ה-API.
למה צריך לבצע את ההעברה
אם האפליקציה שלכם צריכה לגשת לנתונים בנכס Google Analytics 4, צריך לעדכן את הקוד כך שישתמש ב-Data API v1, כי ל-Reporting API v4 יש גישה רק לנכסים שנוצרו באמצעות Universal Analytics.
דרישות מוקדמות
להכיר את היסודות של Data API v1 באמצעות המדריך למתחילים.
איך מתחילים
כדי להתחיל, צריך להכין נכס Google Analytics 4, להפעיל את Data API v1 ואז להגדיר ספריית לקוח של API שמתאימה לפלטפורמה שלכם.
הכנת נכס Google Analytics 4
לפני שמתחילים להעביר את הקוד לתמיכה ב-Data API v1, צריך להעביר את האתר לשימוש בנכס Google Analytics 4. אי אפשר למלא את החוסרים (backfill) בנכס Google Analytics 4 בנתונים היסטוריים מנכס Universal Analytics.
הפעלת ה-API
לחצו על הלחצן הזה כדי להפעיל באופן אוטומטי את Data API v1 בפרויקט Google Cloud שנבחר.
מפעילים את Google Analytics Data API v1שימוש בספריית לקוח
התקן ספריית לקוח
אם אתם משתמשים בספריית לקוח, עליכם להתקין את ספריית הלקוח Data API v1 לשפת התכנות שלכם.
Java
Python
Node.js
.NET
PHP
Go
go get google.golang.org/genproto/googleapis/analytics/data/v1beta
הפעלה של ספריית לקוח
ספריות הלקוח של Data API v1 תוכננו כדי לעזור לך להתחיל לעבוד במהירות. כברירת מחדל, ספריות לקוח מנסות למצוא באופן אוטומטי את פרטי הכניסה לחשבון השירות.
דרך קלה לספק פרטי כניסה לחשבון שירות היא להגדיר את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS. לקוח ה-API ישתמש בערך של המשתנה הזה כדי למצוא את קובץ ה-JSON של מפתח חשבון השירות.
לדוגמה, אפשר להגדיר פרטי כניסה לחשבון שירות על ידי הרצת הפקודה הבאה ושימוש בנתיב לקובץ ה-JSON של חשבון השירות:
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
בהמשך מופיעים קטעי הקוד שמשמשים בדרך כלל לאתחול ספריות הלקוח של Data API v1.
Java
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
Python
# Using a default constructor instructs the client to use the credentials
# specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
client = BetaAnalyticsDataClient()
.NET
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
BetaAnalyticsDataClient client = BetaAnalyticsDataClient.Create();
PHP
// Using a default constructor instructs the client to use the credentials // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable. $client = new BetaAnalyticsDataClient();
Node.js
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
const analyticsDataClient = new BetaAnalyticsDataClient();
במקום להשתמש במשתנה סביבה, אפשר גם להעביר את פרטי פרטי הכניסה למכונה של לקוח API באופן מפורש במהלך האתחול. בהמשך מופיעים קטעי הקוד שמשמשים לאתחול ספריות הלקוח של Data API v1 על ידי העברת פרטי כניסה מפורשים בקוד.
Java
// Explicitly use service account credentials by specifying
// the private key file.
GoogleCredentials credentials =
GoogleCredentials.fromStream(new FileInputStream(credentialsJsonPath));
BetaAnalyticsDataSettings betaAnalyticsDataSettings =
BetaAnalyticsDataSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credentials))
.build();
try (BetaAnalyticsDataClient analyticsData =
BetaAnalyticsDataClient.create(betaAnalyticsDataSettings)) {
Python
# TODO(developer): Uncomment this variable and replace with a valid path to
# the credentials.json file for your service account downloaded from the
# Cloud Console.
# credentials_json_path = "/path/to/credentials.json"
# Explicitly use service account credentials by specifying
# the private key file.
client = BetaAnalyticsDataClient.from_service_account_json(credentials_json_path)
.NET
/**
* TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
* Otherwise, default service account credentials will be derived from
* the GOOGLE_APPLICATION_CREDENTIALS environment variable.
*/
// credentialsJsonPath = "/path/to/credentials.json";
// Explicitly use service account credentials by specifying
// the private key file.
BetaAnalyticsDataClient client = new BetaAnalyticsDataClientBuilder
{
CredentialsPath = credentialsJsonPath
}.Build();
PHP
/**
* @param string $credentialsJsonPath Valid path to the credentials.json file for your service
* account downloaded from the Cloud Console.
* Example: "/path/to/credentials.json"
*/
function client_from_json_credentials(string $credentialsJsonPath)
{
// Explicitly use service account credentials by specifying
// the private key file.
$client = new BetaAnalyticsDataClient([
'credentials' => $credentialsJsonPath
]);
return $client;
}
Node.js
/** TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
*/
// credentialsJsonPath = '/path/to/credentials.json';
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Explicitly use service account credentials by specifying
// the private key file.
const analyticsDataClient = new BetaAnalyticsDataClient({
keyFilename: credentialsJsonPath,
});
לא משתמשים בספריית לקוח
אם השתמשתם ב-Reporting API v4 בלי ספריית לקוח ואתם רוצים להמשיך לעשות זאת גם עם Data API v1, עדיין תוכלו להשתמש בפרטי הכניסה שלכם.
צריך להשתמש במסמך הגילוי והנקודת הקצה ב-HTTP החדש שסופק על ידי ה-Data API:
אם הקוד שלכם מנצל מסמך Discovery, עליכם לעדכן אותו למסמך הגילוי שסופק על ידי Data API v1:
אחרי שמעדכנים את נקודת הקצה, תצטרכו להכיר את מבנה הבקשות והמושגים החדשים של Data API על מנת לעדכן את שאילתת ה-JSON.
הדוחות העיקריים
שיטות הדיווח הזמינות
בגרסה 4 של Reporting API הייתה אפשרות להשתמש בשיטה batchGet כדי לגשת לפונקציונליות הדיווח העיקרית. ב-Data API v1 יש כמה שיטות דיווח מרכזיות שתוכלו לבחור מתוכן:
- runReport – השיטה הזו מחזירה דוח בהתאמה אישית של נתוני האירועים ב-Google Analytics. היא לא תומכת בפונקציונליות של צירים והיא שיטה מועדפת לשאילתות דוחות פשוטות.
- runPivotReport: השיטה הזו מחזירה דוח ציר מותאם אישית של נתוני האירועים ב-Google Analytics. בדומה ל-pivots ב-Reporting API v4, כל ציר מתאר את השורות והעמודות הגלויות של המאפיינים בתגובה לדוח.
- batchRunReports (דוחות אצווה) זו גרסה באצווה של השיטה
runReportשמאפשרת ליצור מספר דוחות באמצעות קריאה אחת ל-API. - batchRunPivotReports (דוחות אצווה) זו גרסת אצווה של השיטה
runPivotReportשמאפשרת ליצור מספר דוחות באמצעות קריאה אחת ל-API.
המטרה של שימוש בכמה שיטות דיווח היא בעיקר נוחות. שיטות מסוימות תומכות בתכונות מורכבות יותר מאחרות (צירים, אצווה), אבל בשאר המקרים יש שיתוף של מבנה בקשות דומה.
שינויים בסכימת API
יכולות הדיווח של Reporting API וגם של Data API נקבעות בעיקר לפי הסכימה שלהן, כלומר המאפיינים והמדדים הנתמכים בשאילתות לדיווח. יש הבדלים משמעותיים בסכימות ה-API בין שני ממשקי ה-API, בגלל ההבדלים הקונספטואליים בין Universal Analytics ל-Google Analytics 4.
- חשוב להכיר את הרשימה הנוכחית של מאפיינים ומדדים שנתמכים על ידי Data API. בשלב זה, כל המאפיינים והמדדים תואמים זה לזה, כך שאין צורך להשתמש ב-Dimensions and Metrics Explorer כדי לקבוע שילובים תואמים. ההתנהגות הזו תשתנה בעתיד.
- ניתן לגשת למאפיינים מותאמים אישית ב-Google Analytics 4 באמצעות תחביר של מאפיינים מותאמים אישית של Data API v1, במקום להשתמש במשבצות המאפיינים ga:dimensionXX ב-Reporting API v4.
- כדי לגשת למדדים מותאמים אישית ב-Google Analytics 4, משתמשים בתחביר של מדדים מותאמים אישית של Data API v1, במקום להשתמש במשבצות המדדים ga:metricXX ב-Reporting API v4.
- מאפיינים ומדדים מסוימים ב-Universal Analytics מקבילים ישירות ל-Google Analytics 4. למידע נוסף, אפשר לעיין בתרשים המקבילות של הסכימה של UA/GA4 API.
- לשמות של מאפיינים ומדדים אין יותר תחילית
ga:ב-Google Analytics 4. - פונקציונליות מסוימת ב-Universal Analytics עדיין לא זמינה ב-GA4 (למשל, שילוב של Campaign Manager, DV360 ו-Search Ads 360). אחרי שהפונקציונליות הזו תוטמע ב-Google Analytics 4, ה-Data API יתמוך בה, ומאפיינים ומדדים חדשים יתווספו לסכימת ה-API.
ישויות
ב-Google Analytics 4 אין קונספט לתצוגות מפורטות (פרופילים) שהושק ב-Universal Analytics. כתוצאה מכך, אין פרמטר viewId בבקשות הדיווח של Data API v1. במקום זאת, צריך לציין מזהה מספרי של נכס Google Analytics 4 בנתיב כתובת ה-URL של הבקשה בזמן קריאה ל-method של Data API v1.
התנהגות זו שונה מ-Reporting API v4, המסתמך על מזהי תצוגה (profile) כדי לזהות את הישות המדווחת.
ממשק API של נתונים גרסה 1
במקרה של Data API v1, יש לציין מזהה מספרי של נכס Google Analytics 4 בנתיב כתובת ה-URL.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
Reporting API גרסה 4
כדי להשתמש ב-Reporting API v4, צריך לציין מזהה של תצוגה מפורטת (פרופיל) ב-Universal Analytics בגוף השאילתה בדוח.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
....
אם אתם משתמשים באחת מספריות הלקוח של Data API, אין צורך לשנות את נתיב כתובת ה-URL של הבקשה באופן ידני. רוב לקוחות ה-API מספקים פרמטר property, שמצפה למחרוזת בפורמט properties/GA4_PROPERTY_ID. במדריך למתחילים מוצגות דוגמאות לשימוש בספריות הלקוח.
טווחי תאריכים
גם ה-Reporting API v4 וגם ה-Data API v1 תומכים בטווחי תאריכים מרובים שצוינו באמצעות השדה dateRanges בבקשת דיווח. שני ממשקי ה-API חולקים את אותו פורמט של קלט תאריך, עם ערכי תאריכים מוחלטים בפורמט YYYY-MM-DD או תאריכים יחסיים כמו yesderday, today, 7daysAgo וכו'.
בקשות Data API v1 מוגבלות ל-4 טווחי תאריכים, בעוד ש-Reporting API v4 מאפשר 2 טווחי תאריכים בבקשת דוח אחת.
לכל dateRange ב-Data API v1 יכול להיות שדה name אופציונלי שיכול לשמש להפניה לטווח התאריכים המתאים בתשובה.
אם לא מציינים name, שם טווח התאריכים נוצר באופן אוטומטי.
כשמציינים מספר טווחי תאריכים בבקשת Data API v1, מאפיין dateRange חדש מתווסף באופן אוטומטי לתגובה, ושם טווח התאריכים משמש כערך של מאפיין. שימו לב שהתנהגות זו שונה מה-Reporting API v4, שמחזירה נתונים מטווח תאריכים כקבוצה של ערכי מדדים בכל שורה.
בקשה ל-Data API v1
נעשה שימוש בשדה name אופציונלי לכל ערך של dateRange בבקשה.
השם של טווח התאריכים ישמש כערך של המאפיין dateRange בתגובה.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
"name": "year_ago"
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
"name": "current_year"
}
]
}
תגובת Data API v1
התגובה כוללת מאפיין dateRange נוסף באופן אוטומטי.
ערך המאפיין dateRange מכיל את השם של טווח תאריכים, שמגיע מהשדה dateRange.name או שנוצר באופן אוטומטי.
....
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "dateRange"
}
],
....
"rows": [
....
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "year_ago"
}
],
"metricValues": [
{
"value": "253286"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "current_year"
}
],
"metricValues": [
{
"value": "272582"
}
]
},
....
בקשה ל-Reporting API v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
]
}
]
}
תגובה של Reporting API v4
ב-Reporting API v4, הערכים של כל טווח תאריכים מקובצים בשדה metrics:
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"253286"
]
},
{
"values": [
"272582"
]
}
]
},
מיון
ניתן לשלוט בהתנהגות של סדר הצגת השאילתות של דוח Data API v1 באמצעות השדה orderBys, בדומה לשדה orderBys ב-Reporting API v4.
המפרט של OrderBy השתנה ב-Data API גרסה 1.
כל OrderBy יכול להכיל אחד מהבאים:
- אם משתמשים ב-DimensionOrderBy, התוצאות מסודרות לפי ערכי המאפיין.
- אם משתמשים ב-MetricOrderBy, התוצאות מסודרות לפי הערכים של המדד.
- PivotOrderBy, משמש בשאילתות צירים וממיינים את התוצאות לפי הערכים של המדד בקבוצת עמודות הצירים.
סוגי הסידור DELTA, SMART ו-HISTOGRAM_BUCKET שנתמכים ב-Reporting API v4 לא מוטמעים ב-Data API v1.
סוג הסדר של OrderType.NUMERIC של Data API v1 זהה לערך של OrderType.DIMENSION_AS_INTEGER של ה-Reporting API גרסה 4.
בקשה ל-Data API v1
בדוגמה הזו מוצגת שאילתה לדוגמה שבה מדווחת על מספר הסשנים לפי מדינה, ומסדרת את השורות לפי המדד sessions בסדר יורד.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
תגובת Data API v1
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "United States"
}
],
"metricValues": [
{
"value": "510449"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "283430"
}
]
},
....
],
"totalSize": 212,
"metadata": {}
}
בקשה ל-Reporting API v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"orderBys": [
{
"fieldName": "ga:sessions",
"sortOrder": "DESCENDING"
}
]
}
]
}
תגובה של Reporting API v4
{
"reports": [
{
....
"data": {
"rows": [
{
"dimensions": [
"United States"
],
"metrics": [
{
"values": [
"510449"
]
}
]
},
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"283430"
]
}
]
},
....
}
]
}
סינון
ניתן להשתמש בסעיפים dimensionFilter ו-metricFilter של Data API v1 על מנת לבקש מה-API להחזיר נתונים רק לערכי מאפיינים או ערכים ספציפיים. הדבר דומה ל-dimensionFilterClauses ו-metricFilterClauses של ה-Reporting API v4.
Data API v1 לא תומך במחרוזות של ביטויי סינון, כמו הסעיף filtersExpression של ה-Reporting API v4. יש לשכתב את הביטויים האלה באמצעות הסעיפים dimensionFilter ו-metricFilter.
בקשה ל-Data API v1
הבקשה לדוגמה מחזירה רשימה של ספירות סשנים לנתיבי דפים מסוימים שבהם המשתמשים ביקרו.
המשפט dimensionFilter משמש כדי להחזיר רק את השורות עם ערכי המאפיין pagePath המתחילים ב-/webstore/ ומכילים את המחרוזת action=a12345.
התנאי metricFilter מבקש מ-method runReport להחזיר רק את השורות עם ערכי המדד sessions שגדולים מ-1,000.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "pagePath"
}
],
"dimensionFilter": {
"andGroup": {
"expressions": [
{
"filter": {
"stringFilter": {
"value": "/webstore/",
"matchType": "BEGINS_WITH"
},
"fieldName": "pagePath"
}
},
{
"filter": {
"stringFilter": {
"matchType": "CONTAINS",
"value": "action=a12345"
},
"fieldName": "pagePath"
}
}
]
}
},
"metricFilter": {
"filter": {
"numericFilter": {
"value": {
"int64Value": 1000
},
"operation": "GREATER_THAN"
},
"fieldName": "sessions"
}
},
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
בקשה ל-Reporting API v4
הבקשה לדוגמה הזו דומה לדוגמה של Data API v1. היא מחזירה רשימה של ספירות סשנים לנתיבי דפים מסוימים שהמשתמשים ביקרו בהם.
השדה dimensionFilterClauses משמש להחזרת השורות רק עם ערכי המאפיינים pagePath המתחילים ב-/webstore/ ומכילים את המחרוזת action=a12345.
השדה metricFilterClauses משמש כדי להחזיר רק את השורות שערכי המדד ga:sessions שלהן גדולים מ-1,000.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:pagePath"
}
],
"metricFilterClauses": [
{
"filters": [
{
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "1000"
}
]
}
],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:pagePath",
"operator": "BEGINS_WITH",
"expressions": [
"/webstore/"
]
},
{
"dimensionName": "ga:pagePath",
"operator": "PARTIAL",
"expressions": [
"action=a12345"
]
}
],
"operator": "AND"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
]
}
חלוקה לדפים
ב-Data API v1 נעשה שימוש בשדות limit והיסט כדי לעבור לדפים של תוצאות תשובות שמתפרשות על פני כמה דפים, ואילו ב-Reporting API v4 נעשה שימוש ב-pageToken וב-pageSize.
בבקשות צירים של Data API v1, צריך להשתמש בשדות limit ו-offset של האובייקט Pivot כדי להטמיע עימוד לכל ציר בנפרד. השדה limit נדרש עכשיו לכל אובייקט Pivot.
כברירת מחדל, Data API v1 מחזיר את 10,000 השורות הראשונות של נתוני אירועים לכל היותר, בעוד שערך ברירת המחדל של Reporting API v4 הוא 1,000 שורות.
המספר הכולל של השורות שתואמות לשאילתה מוחזר באמצעות השדה rowCount בתגובה של Data API v1, שדומה ל-Reporting API v4.
בקשה ל-Data API v1
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"limit": 5,
"offset": 15
}
תגובת Data API v1
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"rowCount": 228,
}
בקשה ל-Reporting API v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"pageSize": 5,
"pageToken": "5"
}
]
}
תגובה של Reporting API v4
{
"reports": [
{
....
"data": {
"rows": [
....
],
....
"rowCount": 225,
},
"nextPageToken": "15"
}
]
}
צבירת מדדים
ב-Data API v1 מחושב ערכי צבירה רק כשהשדה metricAggregations מצוין בבקשה. לעומת זאת, הממשק Reporting API v4 מחזיר את הערך הכולל, המינימום והמקסימום לכל מדד כברירת מחדל, אלא אם השדות hideTotals ו-hideValueRanges מוגדרים כ-true.
בקשה ל-Data API v1
נתוני הצבירה יחושבו רק אם השדה metricAggregations צוין בבקשה.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metricAggregations": [
"TOTAL",
"MAXIMUM",
"MINIMUM"
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
תגובת Data API v1
שורות המדדים המצטברות מוחזרות בשדות totals, minimum ו-maximum של התשובה. בשורות של מדדים נצברים, השדה dimensionValues מכיל ערך מיוחד של RESERVED_TOTAL, RESERVED_MAX או RESERVED_MIN.
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"totals": [
{
"dimensionValues": [
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6026053"
}
]
}
],
"maximums": [
{
"dimensionValues": [
{
"value": "RESERVED_MAX"
},
{
"value": "RESERVED_MAX"
}
],
"metricValues": [
{
"value": "493655"
}
]
}
],
"minimums": [
{
"dimensionValues": [
{
"value": "RESERVED_MIN"
},
{
"value": "RESERVED_MIN"
}
],
"metricValues": [
{
"value": "1"
}
]
}
],
....
}
בקשה ל-Reporting API v4
בקשה לדוגמה להחזרת מספר הסשנים לפי מדינה.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
}
]
}
תגובה של Reporting API v4
השדות totals, minimums ו-maximums מופיעים כברירת מחדל בתגובה של Reporting API גרסה 4.
{
"reports": [
{
"columnHeader": {
....
},
"data": {
"rows": [
....
],
....
"totals": [
{
"values": [
"4493363"
]
}
],
"minimums": [
{
"values": [
"1"
]
}
],
"maximums": [
{
"values": [
"684005"
]
}
]
}
}
]
}
צירים
Data API v1 תומך בפונקציונליות של צירים בשיטות הדיווח runPivotReport ו-batchRunPivotReports.
ה-Reporting API v4 מאפשר לכלול צירים בשאילתות דיווח באמצעות השיטה batchGet.
הטמעת צירים שונה ב-Data API v1 בהשוואה ל-Reporting API v4, כך שכל שורת תגובה מייצגת תא יחיד בטבלה, ואילו ב-Reporting API v4, שורת תגובה יחידה מייצגת שורה שלמה בטבלה.
ממשק API של נתונים גרסה 1
בהמשך מופיע מקטע של תגובה לגרסה 1 של Data API לשאילתה runPivotReport. כל תא בדוח הצירים מוחזר בנפרד:
"rows": [
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
Reporting API גרסה 4
בהמשך מופיע מקטע של תגובה Reporting API v4 לשאילתת batchGet. שורת תגובה אחת מייצגת שורת טבלה שלמה שמכילה את כל ערכי המדדים לטבלת הציר ב-pivotValueRegions:
"data": {
"rows": [
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
ב-Data API v1, כל מאפיין של השאילתה runPivotReport או batchRunPivotReports חייב להיות מוגדר בתוך אובייקט ציר. מאפיין
לא יוצג בדוח אם לא משתמשים בו בשום ציר בשאילתת ציר.
עמודות צירים של Data API v1 מצוינות באמצעות השדה fieldNames במקום השדה dimensions ב-Reporting API v4.
אם רוצים לסנן מאפיינים בבקשת דיווח של Data API v1, יש להשתמש במסנן מאפיינים ברמת הבקשה. היא שונה מה-Reporting API v4, שמקבל את המפרט של dimensionFilterClauses באובייקט ציר.
השדה offset ב-Data API v1 דומה מבחינה פונקציונלית לשדה startGroup ב-Reporting API v4.
השדה limit ב-Data API v1 דומה לערך maxGroupCount של Reporting API v4, וצריך להשתמש בו כדי להגביל את העוצמה של הדוח.
ב-Data API v1 יש תמיכה במספר צירים, כל עוד המכפלה של הפרמטר limit בכל צירים לא עולה על 100,000. Reporting API v4 תומך רק במאפיין ציר אחד.
כברירת מחדל, מאפייני Data API v1 מזמינים אותם בתוך ציר לפי המדד הראשון בדוח. ההתנהגות הזו שונה מה-Reporting API v4, שבו סדר הצירים נקבע לפי סדר יורד של 'סך כל המדדים'. כדי לציין את סדר המיון ב-Data API v1, צריך להשתמש בשדה orderBys במפרט הציר.
בקשה ל-Data API v1
שאילתת ציר ב-Data API v1 יוצרת דוח של ספירת סשנים לפי מדינה, בחלוקה לפי המאפיין browser. שימו לב איך השאילתה משתמשת בשדות orderBys, limit ו-offset כדי לשחזר את ההתנהגות של שאילתה דומה של Reporting API בגרסה 4, ולשמור על הגדרות הסדר והעימוד.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"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"
}
]
}
תגובת Data API v1
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "(not set)"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
}
]
}
],
"rowCount": 234
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Safari"
}
]
},
{
"dimensionValues": [
{
"value": "Edge"
}
]
},
{
"dimensionValues": [
{
"value": "Opera"
}
]
}
],
"rowCount": 124
}
],
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "browser"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "237"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "44"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "22"
}
]
},
....
],
....
}
בקשה ל-Reporting API v4
שאילתת ציר בגרסה 4 של Reporting API יוצרת דוח של ספירות סשנים לפי מדינה, בחלוקה לפי המאפיין ga:browser.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"pivots": [
{
"dimensions": [
{
"name": "ga:browser"
}
],
"startGroup": 3,
"maxGroupCount": 3,
"metrics": [
{
"expression": "ga:sessions"
}
]
}
]
}
]
}
תגובה של Reporting API v4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:country"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:sessions",
"type": "INTEGER"
}
],
"pivotHeaders": [
{
"pivotHeaderEntries": [
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Edge"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Opera"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Samsung Internet"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
}
],
"totalPivotGroupsCount": 19
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"(not set)"
],
"metrics": [
{
"values": [
"781283"
],
"pivotValueRegions": [
{
"values": [
"6923",
"1385",
"66"
]
}
]
}
]
},
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
{
"dimensions": [
"Algeria"
],
"metrics": [
{
"values": [
"23208"
],
"pivotValueRegions": [
{
"values": [
"19252",
"66",
"1582"
]
}
]
}
]
},
....
],
....
}
}
]
}
קבוצות בעלות מאפיינים משותפים (cohorts)
ב-Data API v1 נעשה שימוש במפרט של CohortSpec כדי להגדיר דוחות על קבוצות בעלות מאפיינים משותפים. השדה הזה דומה למפרט של CohortGroup ב-Reporting API v4.
כל המדדים שזמינים ב-Data API v1 תואמים כרגע לשאילתות לגבי קבוצות בעלות מאפיינים משותפים, בעוד ש-Reporting API v4 מאפשר להשתמש רק בקבוצת משנה של מדדים מיוחדים בשאילתה על קבוצה בעלת מאפיינים משותפים.
בבקשה של קבוצה בעלת מאפיינים משותפים בגרסה 1 של Data API, חובה לציין את המדד cohortActiveUsers.
גם ב-Data API v1 וגם ב-Reporting API v4 אפשר ליצור עד 12 קבוצות בעלות מאפיינים משותפים בבקשה אחת.
מדדי ערך חיי המשתמש (LTV) לא נתמכים כרגע ב-Data API v1.
שוויון של מדדי קבוצה בעלת מאפיינים משותפים
אפשר להחליף את רוב המדדים של קבוצה בעלת מאפיינים משותפים שמוגדרים ב-Reporting API v4 בביטוי כדי להשיג תוצאה מקבילה ב-Data API v1, בהתאם לתרשים שבהמשך.
| שם מדד של גרסה 4 של Reporting API | שם או ביטוי של מדד Data API v1 |
|---|---|
| ga:cohortActiveUsers | cohortActiveUsers |
| ga:cohortTotalUsers | cohortTotalUsers |
| ga:cohortRetentionRate | "expression": "cohortActiveUsers/cohortTotalUsers" |
| ga:cohortRevenuePerUser | "expression": "totalRevenue/cohortActiveUsers" |
| ga:cohortVisitDurationPerUser | "expression": "userEngagementDuration/cohortActiveUsers" |
| ga:cohortAppviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortPageviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortSessionsPerUser | "expression": "sessions/cohortActiveUsers" |
| ga:cohortGoalCompletionsPerUser | 'expression': 'eventCount/cohortActiveUsers', בנוסף למסנן מאפיינים לפי eventName שתואם לאירוע השלמת היעד הרצוי. |
בקשה ל-Data API v1
שאילתה לדוגמה שקובעת קבוצה של משתמשים בעלי מאפיינים משותפים (cohort) של משתמשים שהסשן הראשון שלהם התרחש בשבוע של 3 בינואר 2021. מספר המשתמשים הפעילים ושיעור שימור המשתמשים מחושבים לקבוצה בעלת מאפיינים משותפים לאורך 5 שבועות, לפי רמת הפירוט WEEKLY.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"name": "cohort",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
],
"cohortsRange": {
"startOffset": 0,
"endOffset": 4,
"granularity": "WEEKLY"
}
},
"metrics": [
{
"name": "cohortActiveUsers"
},
{
"expression": "cohortActiveUsers/cohortTotalUsers",
"name": "cohortRetentionRate"
}
],
"dimensions": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
]
}
תגובת Data API v1
{
"dimensionHeaders": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
],
"metricHeaders": [
{
"name": "cohortActiveUsers",
"type": "TYPE_INTEGER"
},
{
"name": "cohortRetentionRate",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0000"
}
],
"metricValues": [
{
"value": "4268816"
},
{
"value": "0.999913800857494"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0001"
}
],
"metricValues": [
{
"value": "241580"
},
{
"value": "0.056586926213534013"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0002"
}
],
"metricValues": [
{
"value": "159390"
},
{
"value": "0.037335003597877253"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0003"
}
],
"metricValues": [
{
"value": "131512"
},
{
"value": "0.030804950079453122"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0004"
}
],
"metricValues": [
{
"value": "96793"
},
{
"value": "0.022672482610259947"
}
]
}
],
"totalSize": 5,
"metadata": {}
}
בקשה ל-Reporting API v4
שאילתה לדוגמה שקובעת קבוצה של משתמשים בעלי מאפיינים משותפים (cohort) של משתמשים שהסשן הראשון שלהם התרחש בשבוע של 3 בינואר 2021. מספר המשתמשים הפעילים ושיעור שימור המשתמשים מחושבים עבור הקבוצה בעלת המאפיינים המשותפים לאורך 5 שבועות, לפי רמת הפירוט WEEKLY.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dimensions": [
{
"name": "ga:cohort"
},
{
"name": "ga:cohortNthWeek"
}
],
"metrics": [
{
"expression": "ga:cohortActiveUsers"
},
{
"expression": "ga:cohortRetentionRate"
}
],
"cohortGroup": {
"cohorts": [
{
"name": "cohort",
"type": "FIRST_VISIT_DATE",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
]
}
}
]
}
תגובה של Reporting API v4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:cohort",
"ga:cohortNthWeek"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:cohortActiveUsers",
"type": "INTEGER"
},
{
"name": "ga:cohortRetentionRate",
"type": "PERCENT"
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"cohort",
"0000"
],
"metrics": [
{
"values": [
"40793",
"100.0"
]
}
]
},
{
"dimensions": [
"cohort",
"0001"
],
"metrics": [
{
"values": [
"3883",
"9.518789988478416"
]
}
]
},
{
"dimensions": [
"cohort",
"0002"
],
"metrics": [
{
"values": [
"2165",
"5.307283112298679"
]
}
]
},
{
"dimensions": [
"cohort",
"0003"
],
"metrics": [
{
"values": [
"1703",
"4.174735861544873"
]
}
]
},
{
"dimensions": [
"cohort",
"0004"
],
"metrics": [
{
"values": [
"1484",
"3.637879047875861"
]
}
]
},
{
"dimensions": [
"cohort",
"0005"
],
"metrics": [
{
"values": [
"1103",
"2.7038952761503197"
]
}
]
},
{
"dimensions": [
"cohort",
"0006"
],
"metrics": [
{
"values": [
"933",
"2.28715711028853"
]
}
]
},
{
"dimensions": [
"cohort",
"0007"
],
"metrics": [
{
"values": [
"336",
"0.8236707278209496"
]
}
]
}
],
"totals": [
{
"values": [
"52400",
"16.056676390557204"
]
}
],
"rowCount": 8,
"minimums": [
{
"values": [
"336",
"0.8236707278209496"
]
}
],
"maximums": [
{
"values": [
"40793",
"100.0"
]
}
],
"isDataGolden": true
}
}
]
}
דגימות
ב-Data API v1 נעשה באופן אוטומטי דגימת נתונים כשהמערכת צופה שמגבלות העוצמה יפגעו באיכות הנתונים. במקרה שהתוצאות מטווח תאריכים מסוים נדגמות, השדה metadata של RunReportResponse יכיל את הערך SamplingMetadata תואם, בדומה לשדה samplingLevel שנמצא ב-Reporting API v4.
עדכניות הנתונים
ה-Data API לא מספק מקבילה לשדה isDataGolden של ה-Reporting API v4, ששימש כדי לציין אם כל ההיטים של הדוח הסתיימו. עדיין יכול להיות שאותו דוח יחזיר תוצאות שונות כשתופיע שאילתה במועד מאוחר יותר, בגלל עיבוד נוסף.
פלחים (לא נתמכים)
בשלב זה, פלחים אינם נתמכים ב-Data API v1.
דיווח בזמן אמת
כדאי להשתמש ב-method properties.runRealtimeReport של Data API v1 כדי ליצור דוחות בזמן אמת לנכסי Google Analytics 4. פונקציונליות הדיווח בזמן אמת בנכסי Universal Analytics סופקה על ידי השיטה data.realtime.get, של Google Analytics API v3.
הסכימה של דיווח בזמן אמת של Data API שונה מהסכימה של דיווח בזמן אמת של Analytics API v3, בגלל הבדלים קונספטואליים בין Universal Analytics לבין Google Analytics 4.
בקשה ל-Data API v1
בדוגמה הבאה, כדי לשמר את התנהגות המיון המוגדרת כברירת מחדל ב-Google Analytics API v3, הוספנו אלמנט orderBy אופציונלי לשאילתה של Data API v1.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }],
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
}
תגובת Data API v1
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": ""
}
],
"metricValues": [
{
"value": "199"
}
]
},
{
"dimensionValues": [
{
"value": "Afghanistan"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
],
"metricValues": [
{
"value": "136"
}
]
},
....
],
"rowCount": 172
}
בקשה ל-Google Analytics API v3
GET https://analytics.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&metrics=rt:activeUsers&dimensions=rt:country
תגובה של Google Analytics API v3
{
"kind": "analytics#realtimeData",
"id": "https://www.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&dimensions=rt:country&metrics=rt:activeUsers",
"query": {
"ids": "ga:UA_VIEW_ID",
"dimensions": "rt:country",
"metrics": [
"rt:activeUsers"
],
"max-results": 10
},
"totalResults": 178,
"profileInfo": {
"profileId": "XXXXXX",
"accountId": "XXXXXX",
"webPropertyId": "UA-XXXXXX",
"profileName": "View Name",
},
"columnHeaders": [
{
"name": "rt:country",
"columnType": "DIMENSION",
"dataType": "STRING"
},
{
"name": "rt:activeUsers",
"columnType": "METRIC",
"dataType": "INTEGER"
}
],
"totalsForAllResults": {
"rt:activeUsers": "80351"
},
"rows": [
[
"(not set)",
"97"
],
[
"Afghanistan",
"2"
],
[
"Albania",
"78"
],
....
]
}
(לא נתמך) דיווח על פעילות משתמשים
ב-Data API v1 אין כרגע תמיכה בפונקציונליות של דיווח על פעילויות של משתמשים יחידים, בדומה ל-method userActivity.search של Reporting API v4.
שינויים במכסת API
קטגוריות הליבה והמכסות בזמן אמת
לצורכי המכסה, ה-Data API כולל שתי קטגוריות של בקשות: Core ו-Real-time. בקשות API לשיטות דיווח ליבה (runReport, getMetadata, runPivotReport, batchRunReports, batchRunPivotReports) מחייבות מכסות ליבה.
בקשות API ל-method runRealtimeReport מחייבת מכסות בזמן אמת.
מכסות לאסימונים
בנוסף למכסות בפרויקטים, בכל בקשה נעשה שימוש במכסות לאסימונים של נכסים, שמחויבים בהתאם למורכבות השאילתה. למידע מפורט על המכסות והמגבלות של API, אפשר לעיין במסמכי התיעוד בנושא מכסות של Data API v1.
אפשר לראות את המצב הנוכחי של כל המכסות בנכס Analytics על ידי הגדרת returnPropertyQuota
ל-true בבקשת דיווח ליבה או בזמן אמת. מצב המכסה יוחזר ב-PropertyQuota.
(לא נתמך) מכסה מבוססת משאבים
כל דוחות הליבה ב-Google Analytics 4 מבוססים על נתונים ללא דגימה, לכן המכסה מבוססת-המשאבים שמופעלת ב-Reporting API v4 כבר לא רלוונטית, ולא קיים שדה מקביל בשדה useResourceQuotas שמופיע בבקשת דיווח של Data API v1.
(לא נתמך) מכסה של בקשות לכל צפייה (פרופיל) ליום
בגלל שאין תצוגות מפורטות ב-Google Analytics 4, המכסה requests per view (profile) per day לא קיימת ב-Data API v1 והוחלפה במכסות לאסימונים.