בעזרת משימות של דוחות, תוכלו להתחיל בקשה אסינכרונית ממושכת כדי ליצור דוח בהתאמה אישית של נתוני האירועים ב-Google Analytics.
משאב משימת הדיווח שנוצרת מהבקשה הזו יכול לשמש לגישה לדוחות מותאמים אישית על ידי כל המשתמשים שיש להם גישת קריאה לנכס שלכם ב-Google Analytics.
דוח בהתאמה אישית יהיה זמין למשך 72 שעות אחרי שהוא יהיה מוכן. אחרי התקופה הזו, משאב המשימה של הדוח והתוכן שלה יימחקו באופן אוטומטי.
יצירת משימת דיווח
ב-Google Analytics Data API v1 נעשה שימוש בגישה אסינכרונית כדי ליצור משימות דיווח. קודם כול, צריך בקשה ל-method reportTasks.create
כדי ליצור משימת דוח. לאחר מכן משתמשים בשיטה reportTasks.query
כדי לאחזר את הדוח בהתאמה אישית שנוצר.
בנוסף, אפשר להשתמש ב-reportTasks.get
כדי לאחזר מטא-נתונים של הגדרות של משימת דוח ספציפית, וגם ב-reportTasks.list
כדי להציג רשימה של כל משימות הדיווח בנכס.
צריך לבחור ישות לדיווח
בכל השיטות של Data API v1 צריך לציין את מזהה נכס Google Analytics 4 בתוך נתיב הבקשה לכתובת URL, בפורמט properties/GA4_PROPERTY_ID
. לדוגמה:
POST https://analyticsdata.googleapis.com/v1alpha/properties/GA4_PROPERTY_ID/reportTasks
הדוח נוצר על סמך נתוני האירוע ב-Google Analytics שנאספים בנכס Google Analytics 4 שצוין.
אם אתם משתמשים באחת מספריות הלקוח של Data API, אין צורך לשנות את נתיב כתובת ה-URL של הבקשה באופן ידני.
רוב לקוחות ה-API מספקים פרמטר property
שמצפה למחרוזת בפורמט properties/GA4_PROPERTY_ID
.
במדריך למתחילים מוצגות דוגמאות לשימוש בספריות הלקוח.
שליחת בקשה ליצירת משימת דיווח
כדי ליצור משימת דיווח, צריך לקרוא לשיטה reportTasks.create
באמצעות האובייקט ReportTask
שבבקשה. הפרמטרים הבאים נדרשים:
reportDefinition
שמתאר את ההגדרה של דוח בהתאמה אישית. המבנה של הפרמטר הזה דומה להגדרת הדוח שמשמשת שיטות דיווח ליבה.
בקשה לדוגמה ליצירת משימת דוח:
בקשת HTTP
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
"reportDefinition": {
"dateRanges": [{ "startDate": "2024-05-01"", "endDate": "2024-05-15" }],
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }]
}
}
תשובה משיטת reportTasks.create
מכילה את השם של משימת הדוח בשדה name
(כמו properties/1234567/reportTasks/123
), שבו ניתן להשתמש בשאילתות הבאות כדי לקבל את הסטטוס של משימת דוח ולאחזר את הדוח שמתקבל.
תגובת HTTP
{
"response": {
"@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
"name": "properties/1234567/reportTasks/123",
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "CREATING",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
}
}
}
קבלת מצב המוּכנוּת למשימות
יצירת דוח עשויה להימשך כמה דקות אחרי השיחה ל-reportTasks.create
. אפשר לבדוק את מצב המוּכנוּת של משימת דיווח על ידי קריאה לשיטה reportTasks.get
.
משתמשים בשם של משימת הדיווח (למשל properties/1234567/reportTasks/123
) שקיבלתם מהתגובה של reportTasks.create
כדי לציין את משימת הדיווח.
דוגמה:
בקשת HTTP
GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123
סטטוס המוּכנוּת של משימת דיווח מוחזר בשדה state
של התשובה. אחרי שיצירת הדוח תושלם, המצב של משימת דוח ישתנה מ-CREATING
ל-ACTIVE
.
השדה reportMetadata
מכיל את המידע הכללי על הדוח שנוצר, כמו מספר השורות וכמות אסימוני המכסה שחויבתם.
תגובת HTTP
{
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "ACTIVE",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
"creationQuotaTokensCharged": 6,
"taskRowCount": 167,
"errorMessage": "",
"totalRowCount": 167
}
}
אפשר לבדוק את המצב של כל משימות הדיווח באמצעות קריאה ל-method reportTasks.list
.
אחזור הדוח שנוצר
אחרי שיוצרים את משימת הדיווח באמצעות השיטה reportTasks.create
, קוראים ל-method reportTasks.query
ומציינים את השם של Report Task (למשל properties/1234567/reportTasks/123
).
בקשת HTTP
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query
אם משימת הדיווח מוכנה, תוחזר תשובה עם הדוח שנוצר:
תגובת HTTP
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
...
],
"rowCount": 167,
"metadata": {
"currencyCode": "USD",
"timeZone": "America/Los_Angeles"
}
}