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

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

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

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

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

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

الميزات المشترَكة مع تقارير Core

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

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

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

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

اختيار جهة إعداد التقارير

على غرار وظيفة التقارير الأساسية في الإصدار 1 من Data API، يتطلّب الإجراء runAccessReport في الإصدار 1 من Google Analytics Admin API تحديد معرّف موقع Google Analytics داخل مسار طلب عنوان URL بالتنسيق properties/GA_PROPERTY_ID، على النحو التالي:

  POST  https://analyticsadmin.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runAccessReport

يتم إنشاء تقرير الوصول إلى البيانات الناتج استنادًا إلى سجلّات الوصول إلى البيانات في "إحصاءات Google" للموقع المحدّد على "إحصاءات Google".

إذا كنت تستخدم إحدى مكتبات برامج واجهة Admin API، ليس عليك تعديل مسار عنوان URL للطلب يدويًا. توفّر معظم برامج API المَعلمة property التي تتوقّع سلسلة بالتنسيق properties/GA_PROPERTY_ID. يمكنك الاطّلاع على مقتطف الرمز في بداية هذه الصفحة للحصول على مثال حول كيفية استخدام مكتبات البرامج.

اختيار السمات والمقاييس

تصف السمات بيانات الوصول إلى موقعك وتصنّفها. على سبيل المثال، تشير السمة userEmail إلى البريد الإلكتروني للمستخدم الذي وصل إلى بيانات التقارير. قيم السمات في ردود التقارير هي سلاسل.

تمثّل المقاييس القياسات الكمية للتقرير. يعرض مقياس accessCount إجمالي عدد سجلات الوصول إلى البيانات.

اطّلِع على مخطط الوصول إلى البيانات للحصول على قائمة كاملة بأسماء السمات والمقاييس المتاحة في طلبات تقرير "الوصول إلى البيانات".

طلب التقرير

لطلب تقارير "الوصول إلى البيانات"، أنشئ عنصر RunAccessReportRequest. ننصحك بالبدء بمَعلمات الطلب التالية:

• يجب أن يتضمّن حقل النطاقات الزمنية قيمة واحدة صالحة على الأقل.
• يجب توفُّر قيمة صالحة واحدة على الأقل في حقل السمات.
• في حال عدم استخدام السمة epochTimeMicros، يجب توفّر إدخال صالح واحد على الأقل في الحقل metrics لتلقّي بيانات كمية لكل مجموعة من قيم السمات في التقرير.

في ما يلي نموذج طلب يتضمّن الحقول المقترَحة. سينشئ طلب البحث هذا قائمة بعناوين البريد الإلكتروني للمستخدمين، وآخر مرة وصلوا فيها إلى الموقع المحدّد خلال آخر 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 منذ بداية الحقبة) لكل صف.

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

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

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

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

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

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

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

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

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

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

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

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