نظرة عامة

يتيح لك الإصدار 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 أيام، وعدد أذونات الوصول المقابل.

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.

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

{
  "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) لكل صف.

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

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

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

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

تقرير النظرة العامة على الدخول إلى الموقع

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

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

ويحتوي التقرير على صف واحد لكل تركيبة رقم تعريف الموقع/آلية الوصول.

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

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

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

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

مكتبات العملاء

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

في ما يلي مثال على استخدام مكتبة برامج بايثون التي تشغِّل استعلامًا للوصول إلى البيانات وتطبع الرد.

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