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

يمكنك إنشاء تقارير "الوصول إلى البيانات" باستخدام Admin API v1 runAccessReport method. يعرض لك هذا التقرير كلّ مرّة يقرأ فيها أحد المستخدِمين بيانات "إحصاءات 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 لطلب تقرير "الوصول إلى البيانات".

اختيار كيان إعداد التقارير

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

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

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

إذا كنت تستخدم إحدى مكتبات عملاء Admin API، ليس عليك التلاعب بمسار عنوان URL للطلب يدويًا. يوفّر معظم عملاء واجهة برمجة التطبيقات 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 منذ بدء القياس) لكل صف.

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

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

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

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

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

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

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

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

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

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

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

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