يتيح لك الإصدار 1 من واجهة برمجة التطبيقات Admin API في "إحصاءات Google" إمكانية الوصول إلى التقارير باستخدام
runAccessReport
. يوفّر التقرير سجلات لكل مرة يطّلِع فيها المستخدِم على "إحصاءات Google".
بيانات إعداد التقارير. يتم الاحتفاظ بسجلات إمكانية الوصول لمدة تصل إلى عامين. الوصول إلى البيانات
لا تتوفّر التقارير إلا للمستخدمين الذين لديهم دور المشرف.
إنشاء تقرير الوصول إلى البيانات
يتم توفير تقارير الوصول إلى البيانات بواسطة runAccessReport.
الميزات المشتركة مع "التقارير الأساسية"
تحتوي طلبات تقارير "الوصول إلى البيانات" على الدلالة نفسها في التقرير الأساسي للعديد من الميزات المشتركة. على سبيل المثال: تعمل مواصفات التقسيم على صفحات وفلاتر الأبعاد والنطاقات الزمنية بالطريقة نفسها في تقارير الوصول إلى البيانات باعتبارها التقارير الأساسية.
تعرف على نظرة عامة على الوظيفة الأساسية لإعداد التقارير الإصدار 1 من Data API، كباقي هذه على الميزات الخاصة بطلبات تقرير الوصول إلى البيانات.
اختيار عنصر إعداد التقارير
على غرار إعداد التقارير الأساسية
الوظيفة
الإصدار الأول من Data API، runAccessReport
لـ Google Analytics Admin API v1، يجب توفّر إحصاءات Google
معرّف السمة التي يجب تحديدها داخل
مسار طلب عنوان URL في شكل properties/GA_PROPERTY_ID
، مثل:
POST https://analyticsadmin.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runAccessReport
سيتم إنشاء تقرير الوصول إلى البيانات استنادًا إلى "إحصاءات Google" سجلات الوصول إلى البيانات لموقع "إحصاءات Google" المحدّد
في حال كنت تستخدم إحدى مكتبات عملاء واجهة برمجة التطبيقات Admin API:
ليست هناك حاجة إلى معالجة مسار عنوان URL للطلب يدويًا. معظم عملاء واجهة برمجة التطبيقات
توفير مَعلمة property
التي تتوقع الحصول على سلسلة على شكل
properties/GA_PROPERTY_ID
اطّلع على مقتطف الرمز في
بنهاية هذا الدليل للاطلاع على مثال على استخدام مكتبات العملاء.
المكونات والمقاييس
السمات
بيانات الوصول إلى موقعك ووصفها وتجميعها على سبيل المثال، السمة
تشير القيمة userEmail
إلى عنوان البريد الإلكتروني للمستخدم الذي وصل إلى بيانات إعداد التقارير.
قيم السمات في الردود على التقارير هي سلاسل.
المقاييس
أن تمثل القياسات الكمية لأحد التقارير. مقياس accessCount
تُرجع العدد الإجمالي لسجلات الوصول إلى البيانات.
اطّلع على مخطط الوصول إلى البيانات للحصول على قائمة كاملة بالأبعاد أسماء المقاييس المتوفرة في طلبات تقارير الوصول إلى البيانات.
طلب تقرير الوصول إلى البيانات
لطلب تقارير الوصول إلى البيانات، أنشئ كائن RunAccessReportRequest. أر نوصي بالبدء بمعلمات الطلب التالية:
- إدخال واحد صالح على الأقل في التاريخ النطاقات .
- إدخال واحد صالح على الأقل في السمات .
- في حال عدم استخدام السمة
epochTimeMicros
، يجب توفير إدخال واحد صالح على الأقل في الـ المقاييس لتلقي بيانات كميّة لكل مجموعة من قيم الأبعاد في تقرير.
في ما يلي نموذج طلب يتضمّن الحقول المقترَحة. سيؤدي هذا الاستعلام إلى إنشاء قائمة بعناوين البريد الإلكتروني للمستخدمين، وآخر مرة وصلوا فيها إلى الموقع المحدّد خلال نطاق آخر 7 أيام، وعدد عمليات الوصول المقابلة.
HTTP
POST https://analyticsadmin.googleapis.com/v1beta/properties/GA_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/GA_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
يجمّع السمة سجلات الوصول إلى البيانات لكل مستخدم يصل إلى الموقع.
ويعرض آخر وقت وصول (في نظام التشغيل Unix بالميكرو ثانية منذ
حقبة) لكل صف.
تقرير مفصّل حول أذونات وصول المستخدمين
هناك مثال آخر على التقارير المفيدة وهو تقسيم أذونات وصول المستخدمين حسب أذونات الوصول. الآلية (مثل واجهة مستخدم "إحصاءات Google" وواجهة برمجة التطبيقات وما إلى ذلك).
وقت أحدث إمكانية وصول بوحدات المايكرو | عنوان البريد الإلكتروني للمستخدم | آلية الوصول | عدد أذونات الوصول |
---|---|---|---|
1525220215028367 | Alex@example.net | Firebase | 31 |
1525220215555778 | Alex@example.net | واجهة مستخدم "إحصاءات Google" | 1 |
1525220215022378 | Bola@example.net | واجهة مستخدم "إحصاءات Google" | 65 |
1525220215026389 | Bola@example.net | واجهة برمجة تطبيقات "إحصاءات Google" | 894 |
1525220215025631 | Charlie@example.net | واجهة برمجة تطبيقات "إحصاءات Google" | 67 |
1525220215068325 | Mahan@example.net | إعلانات Google | 3 |
يمكن إنشاء هذا التقرير عن طريق إجراء طلبات بحث
السمات mostRecentAccessEpochTimeMicros
،
userEmail
وaccessMechanism
وaccessCount
المقياس
يحتوي التقرير على صف واحد لكل مجموعة لآلية مستخدم/وصول. تشير رسالة الأشكال البيانية
تحتوي سمة mostRecentAccessEpochTimeMicros
على آخر مرة
إلى الموقع باستخدام آلية الوصول المحددة.
تقرير نظرة عامة على الوصول إلى الموقع
من الممكن إنشاء تقرير لموقع دون التقسيم على المستخدمين الفرديين. على سبيل المثال، يوضِّح التقرير التالي عدد مرّات ظهور الموقع يتم الوصول إليه باستخدام آليات وصول مختلفة:
رقم تعريف الموقع الذي تم الوصول إليه | اسم الموقع الذي تم الوصول إليه | آلية الوصول | عدد أذونات الوصول |
---|---|---|---|
12345678 | DemoApp | Firebase | 31 |
12345678 | DemoApp | واجهة مستخدم "إحصاءات Google" | 624 |
12345678 | DemoApp | إعلانات Google | 83 |
12345678 | DemoApp | واجهة برمجة تطبيقات "إحصاءات Google" | 1744 |
يمكن إنشاء هذا التقرير عن طريق إجراء طلبات بحث
السمات accessedPropertyId
،
accessedPropertyName
وaccessMechanism
وaccessCount
المقياس
يحتوي التقرير على صف واحد لكل مجموعة أرقام تعريف/آلية وصول إلى الموقع.
تقرير عمليات الوصول إلى البيانات الفردية
لإنشاء تقرير يستند فيه كل صف إلى إذن وصول فردي إلى البيانات.
سجل، فاحذف البُعد mostRecentAccessEpochTimeMicros
من طلب البحث
يمكنك استخدام السمة epochTimeMicros
بدلاً من ذلك. ليس من الضروري الاستعلام عن
accessCount
، نظرًا لأن كل صف من التقرير يحتوي على معلومات عن
موضع وصول واحد إلى البيانات.
يحتوي التقرير التالي على معلومات تفصيلية حول كل مرة قام فيها المستخدم دخل إلى الخاصية المحددة.
زمن حقبة Unix بوحدات المايكرو | عنوان البريد الإلكتروني للمستخدم | رقم تعريف الموقع الذي تم الوصول إليه | اسم الموقع الذي تم الوصول إليه | عنوان IP للمستخدم | آلية الوصول | بيانات التكلفة التي تم عرضها | بيانات الأرباح التي تم عرضها |
---|---|---|---|---|---|---|---|
1525220215025371 | Bola@example.net | 12345678 | DemoApp | 1.2.3.1 | واجهة مستخدم "إحصاءات Google" | صحيح | صحيح |
1525220645645645 | Mahan@example.net | 12345678 | DemoApp | 1.2.3.5 | واجهة مستخدم "إحصاءات Google" | خطأ | خطأ |
1525220211312322 | Bola@example.net | 12345678 | DemoApp | 11.22.33.11 | إعلانات Google | صحيح | خطأ |
1525220210234221 | Alex@example.net | 12345678 | DemoApp | 11.22.33.22 | Firebase | خطأ | خطأ |
1525220215028368 | Alex@example.net | 12345678 | DemoApp | 1.2.3.2 | إعلانات Google | خطأ | خطأ |
1525220214234231 | Mahan@example.net | 12345678 | DemoApp | 11.22.33.55 | إعلانات Google | صحيح | صحيح |
1525220423423452 | Charlie@example.net | 12345678 | DemoApp | 1.2.3.3 | واجهة برمجة تطبيقات "إحصاءات Google" | صحيح | خطأ |
1525220132312333 | Mahan@example.net | 12345678 | DemoApp | 1.2.3.5 | إعلانات Google | صحيح | صحيح |
يمكن إنشاء هذا التقرير عن طريق إجراء طلبات بحث
السمات 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}")