ב-Google Analytics Admin API v1 אפשר ליצור דוחות גישה לנתונים באמצעות method runAccessReport
. הדוח מספק רשומות של כל פעם שמשתמש קורא נתוני דיווח של Google Analytics. רשומות הגישה נשמרות עד שנתיים.
דוחות 'גישה לנתונים' זמינים רק למשתמשים בעלי תפקיד מנהל מערכת.
יצירת דוח גישה לנתונים
הדיווח על הרשאות הגישה לנתונים מסופק באמצעות השיטה runAccessReport.
תכונות משותפות עם דוחות ליבה
לבקשות לדוחות גישה לנתונים יש סמנטיקה זהה לזו של בקשות לקבלת דוח ליבה, לגבי הרבה תכונות משותפות. לדוגמה, עימוד, מסנני מאפיינים, המפרט טווחי תאריכים פועלים באותו אופן בדוחות גישה לנתונים כמו דוחות ליבה.
מומלץ לקרוא את הסקירה הכללית על פונקציונליות הדיווח העיקרית של Data API v1, כי שאר המסמך הזה יתמקד בתכונות הספציפיות לבקשות לדוח 'גישה לנתונים'.
בחירת ישות מדווחת
בדומה לפונקציונליות הדיווח העיקרית של Data API v1, גם בשיטת runAccessReport
של Google Analytics Admin API v1, צריך לציין את מזהה נכס Google Analytics 4 בנתיב בקשה לכתובת URL בצורת properties/GA4_PROPERTY_ID
, למשל:
POST https://analyticsadmin.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runAccessReport
דוח הגישה לנתונים שיתקבל יופק על סמך רשומות הגישה לנתונים של Google Analytics בנכס Google Analytics 4 שצוין.
אם אתם משתמשים באחת מספריות הלקוח של Admin API, אין צורך לשנות את נתיב כתובת ה-URL של הבקשה באופן ידני. רוב לקוחות ה-API מספקים פרמטר property
, שמצפה למחרוזת בפורמט properties/GA4_PROPERTY_ID
. ראו את קטע הקוד בסוף המדריך הזה כדי לראות דוגמה לשימוש בספריות הלקוח.
מאפיינים ומדדים
מאפיינים מתארים ומקבצים נתוני גישה לנכס. לדוגמה, המאפיין userEmail
מציין את כתובת האימייל של המשתמש שניגש לנתוני דיווח.
ערכי המאפיינים בתגובות לדוח הם מחרוזות.
מדדים מייצגים את המדידות הכמותיות של דוח. המדד accessCount
מחזיר את המספר הכולל של רשומות גישה לנתונים.
בסכימת הגישה לנתונים יש רשימה מלאה של שמות המאפיינים והמדדים שזמינים בבקשות לדוח גישה לנתונים.
בקשה לדוח גישה לנתונים
כדי לבקש דוחות גישה לנתונים, יוצרים אובייקט RunAccessReportRequest. מומלץ להתחיל עם הפרמטרים הבאים של הבקשה:
- לפחות רשומה חוקית אחת בשדה טווחי תאריכים.
- לפחות רשומה חוקית אחת בשדה מאפיינים.
- אם לא משתמשים במאפיין
epochTimeMicros
, צריך להזין לפחות רשומה חוקית אחת בשדה metrics כדי לקבל נתונים כמותיים לכל שילוב של ערכי מאפיינים בדוח.
הנה בקשה לדוגמה עם השדות המומלצים. השאילתה הזו תיצור רשימה של כתובות האימייל של המשתמשים, את הפעם האחרונה שבה הם ניגשו לנכס שצוין בטווח של 7 הימים האחרונים ואת מספר הרשאות הגישה.
HTTP
POST https://analyticsadmin.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runAccessReport
{
"dateRanges": [
{
"startDate": "7daysAgo",
"endDate": "today"
}
],
"dimensions": [
{
"dimensionName": "mostRecentAccessEpochTimeMicros"
},
{
"dimensionName": "userEmail"
}
],
"metrics": [
{
"metricName": "accessCount"
}
]
}
דיווח על תגובה
באופן עקרוני, פונקציונליות הדיווח הבסיסית של Data API v1, תגובת דוח הגישה לנתונים של בקשת דוח הגישה היא בעיקר כותרת ושורות. הכותרת כוללת את AccessDimensionHeaders
ואת AccessMetricHeaders
, שבהן מפורטות העמודות בדוח.
כל שורת גישה לדוח כוללת את AccessDimensionValues
ואת AccessMetricValues
העמודות בדוח. סדר העמודות עקבי בבקשה, בכותרת ובכל שורה.
הנה תשובה לדוגמה לבקשה לדוגמה הקודמת:
{
"dimensionHeaders": [
{
"dimensionName": "mostRecentAccessEpochTimeMicros"
},
{
"dimensionName": "userEmail"
}
],
"metricHeaders": [
{
"metricName": "accessCount"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "1667591408427733"
},
{
"value": "Bola@example.net"
}
],
"metricValues": [
{
"value": "1238"
}
]
},
{
"dimensionValues": [
{
"value": "1667710959827161"
},
{
"value": "Alex@example.net"
}
],
"metricValues": [
{
"value": "475"
}
]
},
{
"dimensionValues": [
{
"value": "1667868650762743"
},
{
"value": "Mahan@example.net"
}
],
"metricValues": [
{
"value": "96"
}
]
}
],
"rowCount": 3
}
סינון של רשומות גישה
השתמשו בשדה dimensionFilter של האובייקט RunAccessReportRequest כדי להגביל את התגובה בדוח לערכי מאפיינים ספציפיים שתואמים למסנן.
בדוגמה הבאה נוצר דוח שמבוסס על רשומות גישה נפרדות לנתונים, תוך סינון לפי רשומות הגישה של משתמש יחיד עם כתובת האימייל Alex@example.net
. הדוח מכיל את הזמן של כל רשומת גישה, כתובת האימייל וכתובת ה-IP של המשתמש.
HTTP
POST https://analyticsadmin.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runAccessReport
{
"dateRanges": [
{
"startDate": "7daysAgo",
"endDate": "today"
}
],
"dimensions": [
{
"dimensionName": "epochTimeMicros"
},
{
"dimensionName": "userEmail"
},
{
"dimensionName": "userIP"
}
],
"dimensionFilter": {
"accessFilter": {
"fieldName": "userEmail",
"stringFilter": {
"matchType": "EXACT",
"value": "Alex@example.net"
}
}
}
}
באופן דומה, ניתן להשתמש בשדה metricFilter
של האובייקט RunAccessReportRequest
כדי להגביל את התגובה בדוח לערכי מדדים ספציפיים שתואמים למסנן.
בדוגמה הבאה נוצר דוח שמכיל כתובות אימייל ומספרי הרשאות גישה של כל המשתמשים שניגשו לנכס שצוין יותר מ-100 פעמים.
HTTP
{
"dateRanges": [
{
"startDate": "7daysAgo",
"endDate": "today"
}
],
"dimensions": [
{
"dimensionName": "userEmail"
}
],
"metricFilter": {
"accessFilter": {
"numericFilter": {
"operation": "GREATER_THAN",
"value": {
"int64Value": 100
}
},
"fieldName": "accessCount"
}
},
"metrics": [
{
"metricName": "accessCount"
}
]
}
דוחות לדוגמה
הנה כמה דוחות של דגימות שאפשר לנסות.
דוח הגישה האחרונה לכל משתמש
דוח הגישה לדוגמה הבא, שניתן ליצור באמצעות runAccessReport
:
מיקרו-זמן של הגישה האחרונה | כתובת האימייל של המשתמש | מספר הרשאות הגישה |
---|---|---|
1525220215025371 | Bola@example.net | 5 |
1525220215028361 | Alex@example.net | 36 |
1525220215027671 | Charlie@example.net | 1153 |
1525220215027341 | Mahan@example.net | 1 |
ניתן ליצור את הדוח הזה באמצעות שאילתה על המאפיינים
mostRecentAccessEpochTimeMicros
, userEmail
ועל המדד accessCount
. הדוח מכיל שורה אחת לכל משתמש: המאפיין mostRecentAccessEpochTimeMicros
צובר רשומות גישה לנתונים של כל משתמש שניגש לנכס ומחזיר את זמן הגישה האחרון (במיליוניות השנייה מאז תחילת התקופה של זמן מערכת) של כל שורה.
דוח פירוט הרשאות גישה של משתמשים
דוגמה נוספת לדוח שימושי היא פירוט של הרשאות הגישה של משתמשים לפי מנגנון גישה (למשל, ממשק משתמש של Google Analytics, API וכו').
מיקרו-זמן של הגישה האחרונה | כתובת האימייל של המשתמש | מנגנון גישה | מספר הרשאות הגישה |
---|---|---|---|
1525220215028367 | Alex@example.net | Firebase | 31 |
1525220215555778 | Alex@example.net | ממשק המשתמש של Google Analytics | 1 |
1525220215022378 | Bola@example.net | ממשק המשתמש של Google Analytics | 65 |
1525220215026389 | Bola@example.net | ממשק API של Google Analytics | 894 |
1525220215025631 | Charlie@example.net | ממשק API של Google Analytics | 67 |
1525220215068325 | Mahan@example.net | Google Ads | 3 |
ניתן ליצור את הדוח על ידי שליחת שאילתה למאפיינים
mostRecentAccessEpochTimeMicros
, userEmail
, accessMechanism
והמדד accessCount
.
הדוח מכיל שורה אחת לכל שילוב של משתמש/מנגנון גישה. המאפיין
mostRecentAccessEpochTimeMicros
מכיל את הפעם האחרונה שבה משתמש נכנס לנכס באמצעות מנגנון הגישה שצוין.
הדוח 'סקירה כללית על גישה לנכס'
אפשר ליצור דוח לנכס בלי להציג פירוט של משתמשים ספציפיים. לדוגמה, הדוח הבא מציין באיזו תדירות מתבצעת גישה לנכס באמצעות מנגנוני גישה שונים:
מזהה נכס שבוצעה אליו גישה | שם נכס שבוצעה אליו גישה | מנגנון גישה | מספר הרשאות הגישה |
---|---|---|---|
12345678 | DemoApp | Firebase | 31 |
12345678 | DemoApp | ממשק המשתמש של Google Analytics | 624 |
12345678 | DemoApp | Google Ads | 83 |
12345678 | DemoApp | ממשק API של Google Analytics | 1744 |
כדי ליצור את הדוח אפשר להריץ שאילתות על המאפיינים accessedPropertyId
, accessedPropertyName
, accessMechanism
והמדד accessCount
.
הדוח מכיל שורה אחת לכל שילוב של מזהה נכס ומנגנון גישה.
דוח 'גישה לנתונים נפרדים'
כדי ליצור דוח שבו כל שורה מבוססת על רשומה נפרדת של גישה לנתונים, משמיטים את המאפיין mostRecentAccessEpochTimeMicros
מהשאילתה ומשתמשים במקום זאת במאפיין epochTimeMicros
. אין צורך להריץ שאילתה על המדד accessCount
, כי כל שורה בדוח מכילה מידע על אירוע יחיד של גישה לנתונים.
הדוח הבא מכיל מידע מפורט על כל פעם שמשתמש ניגש לנכס שצוין.
Micros זמן | כתובת האימייל של המשתמש | מזהה נכס שבוצעה אליו גישה | שם נכס שבוצעה אליו גישה | כתובת IP של משתמש | מנגנון גישה | נתוני עלות שהוחזרו | נתוני הכנסות שהוחזרו |
---|---|---|---|---|---|---|---|
1525220215025371 | Bola@example.net | 12345678 | DemoApp | 1.2.3.1 | ממשק המשתמש של Google Analytics | true | true |
1525220645645645 | Mahan@example.net | 12345678 | DemoApp | 1.2.3.5 | ממשק המשתמש של Google Analytics | false | false |
1525220211312322 | Bola@example.net | 12345678 | DemoApp | 11.22.33.11 | Google Ads | true | false |
1525220210234221 | Alex@example.net | 12345678 | DemoApp | 11.22.33.22 | Firebase | false | false |
1525220215028368 | Alex@example.net | 12345678 | DemoApp | 1.2.3.2 | Google Ads | false | false |
1525220214234231 | Mahan@example.net | 12345678 | DemoApp | 11.22.33.55 | Google Ads | true | true |
1525220423423452 | Charlie@example.net | 12345678 | DemoApp | 1.2.3.3 | ממשק API של Google Analytics | true | false |
1525220132312333 | Mahan@example.net | 12345678 | DemoApp | 1.2.3.5 | Google Ads | true | true |
ניתן ליצור את הדוח הזה על ידי שליחת שאילתה למאפיינים
epochTimeMicros
, userEmail
, accessedPropertyId
, accessedPropertyName
,
userIP
, accessMechanism
, costDataReturned
, revenueDataReturned
.
ספריות לקוח
במדריך למתחילים מוסבר איך להתקין ולהגדיר ספריות לקוח.
זוהי דוגמה לשימוש בספריית הלקוח של Python שמריצה שאילתת גישה לנתונים ומדפיסה את התגובה.
Python
from datetime import datetime from google.analytics.admin import AnalyticsAdminServiceClient from google.analytics.admin_v1alpha.types import ( AccessDateRange, AccessDimension, AccessMetric, RunAccessReportRequest, ) def run_sample(): """Runs the sample.""" # TODO(developer): Replace this variable with your Google Analytics 4 # property ID (e.g. "123456") before running the sample. property_id = "YOUR-GA4-PROPERTY-ID" run_access_report(property_id) def run_access_report(property_id: str, transport: str = None): """ Runs an access report for a Google Analytics property. The report will aggregate over dimensions `userEmail`, `accessedPropertyId`, `reportType`, `revenueDataReturned`, `costDataReturned`, `userIP`, and return the access count, as well as the most recent access time for each combination. See https://developers.google.com/analytics/devguides/config/admin/v1/access-api-schema for the description of each field used in a data access report query. Args: property_id(str): The Google Analytics Property ID. transport(str): The transport to use. For example, "grpc" or "rest". If set to None, a transport is chosen automatically. """ client = AnalyticsAdminServiceClient(transport=transport) request = RunAccessReportRequest( entity=f"properties/{property_id}", dimensions=[ AccessDimension(dimension_name="userEmail"), AccessDimension(dimension_name="accessedPropertyId"), AccessDimension(dimension_name="reportType"), AccessDimension(dimension_name="revenueDataReturned"), AccessDimension(dimension_name="costDataReturned"), AccessDimension(dimension_name="userIP"), AccessDimension(dimension_name="mostRecentAccessEpochTimeMicros"), ], metrics=[AccessMetric(metric_name="accessCount")], date_ranges=[AccessDateRange(start_date="yesterday", end_date="today")], ) access_report = client.run_access_report(request) print("Result:") print_access_report(access_report) def print_access_report(response): """Prints the access report.""" print(f"{response.row_count} rows received") for dimensionHeader in response.dimension_headers: print(f"Dimension header name: {dimensionHeader.dimension_name}") for metricHeader in response.metric_headers: print(f"Metric header name: {metricHeader.metric_name})") for rowIdx, row in enumerate(response.rows): print(f"\nRow {rowIdx}") for i, dimension_value in enumerate(row.dimension_values): dimension_name = response.dimension_headers[i].dimension_name if dimension_name.endswith("Micros"): # Convert microseconds since Unix Epoch to datetime object. dimension_value_formatted = datetime.utcfromtimestamp( int(dimension_value.value) / 1000000 ) else: dimension_value_formatted = dimension_value.value print(f"{dimension_name}: {dimension_value_formatted}") for i, metric_value in enumerate(row.metric_values): metric_name = response.metric_headers[i].metric_name print(f"{metric_name}: {metric_value.value}")