يتيح لك الإصدار 1 من Google Analytics Admin API إنشاء تقارير وصول إلى البيانات باستخدام طريقة runAccessReport
. يوفر التقرير سجلات لكل مرة يطّلع فيها المستخدم على بيانات إعداد التقارير في "إحصاءات Google". يتم الاحتفاظ بسجلّات الوصول لمدة تصل إلى عامَين.
لا تتوفّر تقارير "الوصول إلى البيانات" إلا للمستخدمين الذين لديهم دور المشرف.
إنشاء تقرير الوصول إلى البيانات
يتم توفير إعداد تقارير الوصول إلى البيانات من خلال طريقة runAccessReport.
الميزات المشتركة مع التقارير الأساسية
تتسم طلبات تقارير الوصول إلى البيانات بالدلالات نفسها مع طلبات التقارير الأساسية، للكثير من الميزات المشتركة. على سبيل المثال، تتّبع مواصفات التقسيم على صفحات وفلاتر السمات والنطاقات الزمنية نفس المواصفات في تقارير الوصول إلى البيانات مثل التقارير الأساسية.
اطّلع على نظرة عامة على وظيفة إعداد التقارير الأساسية للإصدار 1 من Data API، حيث سيركّز الجزء المتبقي من هذا المستند على الميزات الخاصة بطلبات تقرير الوصول إلى البيانات.
اختيار كيان لإعداد التقارير
على غرار وظيفة إعداد التقارير الأساسية
للإصدار 1 من Data API، تتطلّب طريقة runAccessReport
للإصدار 1 من Google Analytics Admin API تحديد
معرّف موقع "إحصاءات Google 4"
داخل مسار طلب عنوان URL على شكل
properties/GA4_PROPERTY_ID
، مثل:
POST https://analyticsadmin.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runAccessReport
سيتم إنشاء تقرير الوصول إلى البيانات استنادًا إلى سجلات الوصول إلى بيانات "إحصاءات Google" لموقع "إحصاءات Google 4" المحدّد.
إذا كنت تستخدم إحدى مكتبات عملاء واجهة برمجة التطبيقات Admin API، لن تكون هناك حاجة لمعالجة مسار عنوان URL للطلب يدويًا. توفّر معظم برامج واجهات برمجة التطبيقات
مَعلمة 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، يكون استجابة تقرير الوصول إلى البيانات لطلب تقرير الوصول هو عنوان وصفوف في المقام الأول. يتكون العنوان من رمزَي 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
سجلات الوصول إلى البيانات لكل مستخدم يصل إلى الموقع، وتعرض آخر وقت وصول (بالميكرو ثانية منذ تاريخ بدء 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
، لأنّ كل صف من التقرير يحتوي على معلومات عن حالة واحدة للوصول إلى البيانات.
يتضمّن التقرير التالي معلومات تفصيلية حول كل مرة يصل فيها المستخدم إلى الموقع المحدّد.
وقت الحقبة بالمايكرو | عنوان البريد الإلكتروني للمستخدم | رقم تعريف الموقع الذي تم الوصول إليه | اسم الموقع الذي تم الوصول إليه | عنوان IP للمستخدم | آلية الوصول | بيانات التكلفة التي تم إرجاعها | بيانات الأرباح التي تم إرجاعها |
---|---|---|---|---|---|---|---|
1525220215025371 | Bola@example.net | 12345678 | DemoApp | 1.2.3.1 | واجهة مستخدم "إحصاءات Google" | صحيح | صحيح |
1525220645645645 | Mahan@example.net | 12345678 | DemoApp | 1.2.3.5 | واجهة مستخدم "إحصاءات Google" | false | false |
1525220211312322 | Bola@example.net | 12345678 | DemoApp | 11.22.33.11 | إعلانات Google | صحيح | 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 | false | false |
1525220214234231 | Mahan@example.net | 12345678 | DemoApp | 11.22.33.55 | إعلانات Google | صحيح | صحيح |
1525220423423452 | Charlie@example.net | 12345678 | DemoApp | 1.2.3.3 | واجهة برمجة تطبيقات "إحصاءات Google" | صحيح | false |
1525220132312333 | Mahan@example.net | 12345678 | DemoApp | 1.2.3.5 | إعلانات Google | صحيح | صحيح |
يمكن إنشاء هذا التقرير من خلال طلبات البحث عن السمات
epochTimeMicros
وuserEmail
وaccessedPropertyId
وaccessedPropertyName
و
userIP
وaccessMechanism
وcostDataReturned
وrevenueDataReturned
.
مكتبات العملاء
راجِع دليل البدء السريع للحصول على شرح حول كيفية تثبيت مكتبات العملاء وضبطها.
في ما يلي مثال على استخدام مكتبة برامج بايثون التي تشغِّل استعلامًا للوصول إلى البيانات وتطبع الرد.
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}")