نظرة عامة

يتيح لك الإصدار 1 من واجهة برمجة التطبيقات Admin API في "إحصاءات 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 أيام، وعدد عمليات الوصول المقابلة.

HTTP

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.

HTTP

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

HTTP

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

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

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

أحدث تقرير لكل مستخدم

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

وقت أحدث إمكانية وصول بوحدات المايكرو عنوان البريد الإلكتروني للمستخدم عدد أذونات الوصول
1525220215025371 Bola@example.net 5
1525220215028361 Alex@example.net 36
1525220215027671 Charlie@example.net 1153
1525220215027341 Mahan@example.net 1

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

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

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

وقت أحدث إمكانية وصول بوحدات المايكرو عنوان البريد الإلكتروني للمستخدم آلية الوصول عدد أذونات الوصول
1525220215028367 Alex@example.net Firebase 31
1525220215555778 Alex@example.net واجهة مستخدم "إحصاءات Google" 1
1525220215022378 Bola@example.net واجهة مستخدم "إحصاءات Google" 65
1525220215026389 Bola@example.net واجهة برمجة تطبيقات "إحصاءات Google" 894
1525220215025631 Charlie@example.net واجهة برمجة تطبيقات "إحصاءات Google" 67
1525220215068325 Mahan@example.net إعلانات Google 3

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

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

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

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

رقم تعريف الموقع الذي تم الوصول إليه اسم الموقع الذي تم الوصول إليه آلية الوصول عدد أذونات الوصول
12345678 DemoApp Firebase 31
12345678 DemoApp واجهة مستخدم "إحصاءات Google" 624
12345678 DemoApp إعلانات Google 83
12345678 DemoApp واجهة برمجة تطبيقات "إحصاءات Google" 1744

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

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

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

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

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

زمن حقبة Unix بوحدات المايكرو عنوان البريد الإلكتروني للمستخدم رقم تعريف الموقع الذي تم الوصول إليه اسم الموقع الذي تم الوصول إليه عنوان IP للمستخدم آلية الوصول بيانات التكلفة التي تم عرضها بيانات الأرباح التي تم عرضها
1525220215025371 Bola@example.net 12345678 DemoApp 1.2.3.1 واجهة مستخدم "إحصاءات Google" صحيح صحيح
1525220645645645 Mahan@example.net 12345678 DemoApp 1.2.3.5 واجهة مستخدم "إحصاءات Google" خطأ خطأ
1525220211312322 Bola@example.net 12345678 DemoApp 11.22.33.11 إعلانات Google صحيح خطأ
1525220210234221 Alex@example.net 12345678 DemoApp 11.22.33.22 Firebase خطأ خطأ
1525220215028368 Alex@example.net 12345678 DemoApp 1.2.3.2 إعلانات Google خطأ خطأ
1525220214234231 Mahan@example.net 12345678 DemoApp 11.22.33.55 إعلانات Google صحيح صحيح
1525220423423452 Charlie@example.net 12345678 DemoApp 1.2.3.3 واجهة برمجة تطبيقات "إحصاءات Google" صحيح خطأ
1525220132312333 Mahan@example.net 12345678 DemoApp 1.2.3.5 إعلانات Google صحيح صحيح

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

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

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

في ما يلي مثال على استخدام مكتبة برامج Python التي تُجري طلب وصول إلى البيانات ويطبع الرد.

Python

google-analytics-admin/properties_run_access_report.py
الفتح في Cloud Shell العرض على GitHub 
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