نظرة عامة

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

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

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

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

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

تعرف على نظرة عامة على الوظيفة الأساسية لإعداد التقارير الإصدار 1 من Data API، كباقي هذه على الميزات الخاصة بطلبات تقرير الوصول إلى البيانات.

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

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

الإبلاغ عن الرد

من الناحية النظرية، تشبه التقارير الأساسية لإعداد التقارير لوظيفة Data API v1 تقرير الوصول إلى البيانات الردّ طلب تقرير الوصول عبارة عن عنوان وصفوف بشكل أساسي. يتكون العنوان من 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

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

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

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