تقارير الوصول إلى البيانات

يمكنك إنشاء تقارير "الوصول إلى البيانات" باستخدام طريقة Admin API v1 runAccessReport. يعرض لك هذا التقرير كل مرة يقرأ فيها مستخدم بيانات "إحصاءات Google". يتم الاحتفاظ بسجلّات الوصول إلى البيانات لمدة تصل إلى عامَين. لا تتوفّر تقارير الوصول إلى البيانات إلا للمستخدمين الذين لديهم دور المشرف.

طلب تقرير الوصول إلى البيانات باستخدام مكتبة العميل

أسرع طريقة لبدء استخدام تقارير "الوصول إلى البيانات" هي استخدام مكتبات العملاء.

يمكنك الاطّلاع على دليل البدء السريع للحصول على شرح حول كيفية تثبيت مكتبات برامج "إحصاءات Google" وضبطها.

في ما يلي مثال يستخدم مكتبة برامج 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}")

properties_run_access_report.py

الميزات المشتركة مع التقارير الأساسية

تتضمّن طلبات تقارير "الوصول إلى البيانات" الدلالات نفسها التي تتضمّنها طلبات التقارير الأساسية للعديد من الميزات الشائعة. على سبيل المثال، تعمل تقسيم الصفحات وفلاتر السمات والنطاقات الزمنية بالطريقة نفسها في كلا نوعَي التقارير.

تعرَّف على نظرة عامة على التقارير الأساسية في الإصدار 1 من Data API، ثم ارجع إلى هذه الصفحة لمعرفة المزيد عن تقارير "الوصول إلى البيانات".

إنشاء تقرير الوصول إلى البيانات

استخدِم طريقة runAccessReport لطلب تقرير "الوصول إلى البيانات".

اختيار جهة إبلاغ

على غرار وظيفة إعداد التقارير الأساسية في الإصدار الأول من Data API، يتطلّب إجراء runAccessReport في الإصدار الأول من Google Analytics Admin API تحديد معرّف الموقع على "إحصاءات 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 أيام، وعدد مرات الوصول المقابلة.

POST https://analyticsadmin.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runAccessReport
{
  "dateRanges": [
    {
      "startDate": "7daysAgo",
      "endDate": "today"
    }
  ],
  "dimensions": [
    {
      "dimensionName": "mostRecentAccessEpochTimeMicros"
    },
    {
      "dimensionName": "userEmail"
    }
  ],
  "metrics": [
    {
      "metricName": "accessCount"
    }
  ]
}

قراءة الردّ

يتكوّن ردّ تقرير الوصول إلى البيانات بشكل أساسي من عنوان وصفوف. يتكوّن العنوان من 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.

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 مرة.

{
  "dateRanges": [
    {
      "startDate": "7daysAgo",
      "endDate": "today"
    }
  ],
  "dimensions": [
    {
      "dimensionName": "userEmail"
    }
  ],
  "metricFilter": {
    "accessFilter": {
      "numericFilter": {
        "operation": "GREATER_THAN",
        "value": {
          "int64Value": 100
        }
      },
      "fieldName": "accessCount"
    }
  },
  "metrics": [
    {
      "metricName": "accessCount"
    }
  ]
}

أمثلة على التقارير

في ما يلي بعض نماذج التقارير التي يمكنك تجربتها.

آخر وصول

في ما يلي نموذج تقرير الوصول الذي يمكن إنشاؤه باستخدام runAccessReport:

يمكن إنشاء هذا التقرير من خلال طلب البحث عن السمات mostRecentAccessEpochTimeMicros وuserEmail والمقياس accessCount. يحتوي التقرير على صف واحد لكل مستخدم: تجمع سمة mostRecentAccessEpochTimeMicros بيانات مجمّعة سجلات الوصول إلى البيانات لكل مستخدم يصل إلى الموقع وتعرض وقت آخر وصول (بالوحدات الزمنية Unix microseconds since the epoch) لكل صف.

تقسيم وصول المستخدمين

مثال آخر على تقرير مفيد هو تقسيم عمليات وصول المستخدمين حسب آلية الوصول (مثل واجهة مستخدم "إحصاءات Google" وواجهة برمجة التطبيقات وما إلى ذلك).

يمكن إنشاء هذا التقرير من خلال طلب البحث عن السمات mostRecentAccessEpochTimeMicros وuserEmail وaccessMechanism والمقياس accessCount.

يحتوي التقرير على صف واحد لكل مجموعة من المستخدمين/آليات الوصول. تحتوي السمة mostRecentAccessEpochTimeMicros على آخر مرة وصل فيها المستخدم إلى الموقع باستخدام آلية الوصول المحدّدة.

نظرة عامة على أذونات الوصول إلى الموقع

يمكن إنشاء تقرير لموقع إلكتروني بدون تقسيمه إلى مستخدمين فرديين. على سبيل المثال، يوضّح التقرير التالي عدد مرات الوصول إلى موقع إلكتروني باستخدام آليات وصول مختلفة:

يمكن إنشاء هذا التقرير من خلال طلب البحث عن السمات accessedPropertyId وaccessedPropertyName وaccessMechanism والمقياس accessCount.

يحتوي التقرير على صف واحد لكل مجموعة من معرّفات المواقع وآليات الوصول.

الوصول إلى البيانات الفردية

لإنشاء تقرير يستند فيه كل صف إلى سجلّ وصول فردي إلى البيانات، يمكنك حذف السمة mostRecentAccessEpochTimeMicros من طلب البحث واستخدام السمة epochTimeMicros بدلاً منها. ليس من الضروري الاستعلام عن المقياس accessCount، لأنّ كل صف في التقرير يحتوي على معلومات عن حدث واحد للوصول إلى البيانات.

يحتوي التقرير التالي على معلومات تفصيلية عن كل مرة وصل فيها مستخدم إلى الموقع المحدّد.

يمكن إنشاء هذا التقرير من خلال طلب البحث عن السمات epochTimeMicros وuserEmail وaccessedPropertyId وaccessedPropertyName وuserIP وaccessMechanism وcostDataReturned وrevenueDataReturned.