סקירה כללית

ב-Google Analytics Admin API v1 אפשר ליצור דוחות גישה לנתונים באמצעות method runAccessReport. הדוח מספק רשומות של כל פעם שמשתמש קורא נתוני דיווח של Google Analytics. רשומות הגישה נשמרות עד שנתיים. דוחות 'גישה לנתונים' זמינים רק למשתמשים בעלי תפקיד מנהל מערכת.

יצירת דוח גישה לנתונים

הדיווח על הרשאות הגישה לנתונים מסופק באמצעות השיטה runAccessReport.

תכונות משותפות עם דוחות ליבה

לבקשות לדוחות גישה לנתונים יש סמנטיקה זהה לזו של בקשות לקבלת דוח ליבה, לגבי הרבה תכונות משותפות. לדוגמה, עימוד, מסנני מאפיינים, המפרט טווחי תאריכים פועלים באותו אופן בדוחות גישה לנתונים כמו דוחות ליבה.

מומלץ לקרוא את הסקירה הכללית על פונקציונליות הדיווח העיקרית של Data API v1, כי שאר המסמך הזה יתמקד בתכונות הספציפיות לבקשות לדוח 'גישה לנתונים'.

בחירת ישות מדווחת

בדומה לפונקציונליות הדיווח העיקרית של Data API v1, גם בשיטת runAccessReport של Google Analytics Admin API v1, צריך לציין את מזהה נכס Google Analytics 4 בנתיב בקשה לכתובת URL בצורת properties/GA4_PROPERTY_ID, למשל:

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

דוח הגישה לנתונים שיתקבל יופק על סמך רשומות הגישה לנתונים של Google Analytics בנכס Google Analytics 4 שצוין.

אם אתם משתמשים באחת מספריות הלקוח של Admin API, אין צורך לשנות את נתיב כתובת ה-URL של הבקשה באופן ידני. רוב לקוחות ה-API מספקים פרמטר property, שמצפה למחרוזת בפורמט properties/GA4_PROPERTY_ID. ראו את קטע הקוד בסוף המדריך הזה כדי לראות דוגמה לשימוש בספריות הלקוח.

מאפיינים ומדדים

מאפיינים מתארים ומקבצים נתוני גישה לנכס. לדוגמה, המאפיין userEmail מציין את כתובת האימייל של המשתמש שניגש לנתוני דיווח. ערכי המאפיינים בתגובות לדוח הם מחרוזות.

מדדים מייצגים את המדידות הכמותיות של דוח. המדד accessCount מחזיר את המספר הכולל של רשומות גישה לנתונים.

בסכימת הגישה לנתונים יש רשימה מלאה של שמות המאפיינים והמדדים שזמינים בבקשות לדוח גישה לנתונים.

בקשה לדוח גישה לנתונים

כדי לבקש דוחות גישה לנתונים, יוצרים אובייקט RunAccessReportRequest. מומלץ להתחיל עם הפרמטרים הבאים של הבקשה:

  • לפחות רשומה חוקית אחת בשדה טווחי תאריכים.
  • לפחות רשומה חוקית אחת בשדה מאפיינים.
  • אם לא משתמשים במאפיין epochTimeMicros, צריך להזין לפחות רשומה חוקית אחת בשדה metrics כדי לקבל נתונים כמותיים לכל שילוב של ערכי מאפיינים בדוח.

הנה בקשה לדוגמה עם השדות המומלצים. השאילתה הזו תיצור רשימה של כתובות האימייל של המשתמשים, את הפעם האחרונה שבה הם ניגשו לנכס שצוין בטווח של 7 הימים האחרונים ואת מספר הרשאות הגישה.

HTTP

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 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/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 פעמים.

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 צובר רשומות גישה לנתונים של כל משתמש שניגש לנכס ומחזיר את זמן הגישה האחרון (במיליוניות השנייה מאז תחילת התקופה של זמן מערכת) של כל שורה.

דוח פירוט הרשאות גישה של משתמשים

דוגמה נוספת לדוח שימושי היא פירוט של הרשאות הגישה של משתמשים לפי מנגנון גישה (למשל, ממשק משתמש של Google Analytics, API וכו').

מיקרו-זמן של הגישה האחרונה כתובת האימייל של המשתמש מנגנון גישה מספר הרשאות הגישה
1525220215028367 Alex@example.net Firebase 31
1525220215555778 Alex@example.net ממשק המשתמש של Google Analytics 1
1525220215022378 Bola@example.net ממשק המשתמש של Google Analytics 65
1525220215026389 Bola@example.net ממשק API של Google Analytics 894
1525220215025631 Charlie@example.net ממשק API של Google Analytics 67
1525220215068325 Mahan@example.net Google Ads 3

ניתן ליצור את הדוח על ידי שליחת שאילתה למאפיינים mostRecentAccessEpochTimeMicros, userEmail, accessMechanism והמדד accessCount.

הדוח מכיל שורה אחת לכל שילוב של משתמש/מנגנון גישה. המאפיין mostRecentAccessEpochTimeMicros מכיל את הפעם האחרונה שבה משתמש נכנס לנכס באמצעות מנגנון הגישה שצוין.

הדוח 'סקירה כללית על גישה לנכס'

אפשר ליצור דוח לנכס בלי להציג פירוט של משתמשים ספציפיים. לדוגמה, הדוח הבא מציין באיזו תדירות מתבצעת גישה לנכס באמצעות מנגנוני גישה שונים:

מזהה נכס שבוצעה אליו גישה שם נכס שבוצעה אליו גישה מנגנון גישה מספר הרשאות הגישה
12345678 DemoApp Firebase 31
12345678 DemoApp ממשק המשתמש של Google Analytics 624
12345678 DemoApp Google Ads 83
12345678 DemoApp ממשק API של Google Analytics 1744

כדי ליצור את הדוח אפשר להריץ שאילתות על המאפיינים accessedPropertyId, accessedPropertyName, accessMechanism והמדד accessCount.

הדוח מכיל שורה אחת לכל שילוב של מזהה נכס ומנגנון גישה.

דוח 'גישה לנתונים נפרדים'

כדי ליצור דוח שבו כל שורה מבוססת על רשומה נפרדת של גישה לנתונים, משמיטים את המאפיין mostRecentAccessEpochTimeMicros מהשאילתה ומשתמשים במקום זאת במאפיין epochTimeMicros. אין צורך להריץ שאילתה על המדד accessCount, כי כל שורה בדוח מכילה מידע על אירוע יחיד של גישה לנתונים.

הדוח הבא מכיל מידע מפורט על כל פעם שמשתמש ניגש לנכס שצוין.

Micros זמן כתובת האימייל של המשתמש מזהה נכס שבוצעה אליו גישה שם נכס שבוצעה אליו גישה כתובת IP של משתמש מנגנון גישה נתוני עלות שהוחזרו נתוני הכנסות שהוחזרו
1525220215025371 Bola@example.net 12345678 DemoApp 1.2.3.1 ממשק המשתמש של Google Analytics true true
1525220645645645 Mahan@example.net 12345678 DemoApp 1.2.3.5 ממשק המשתמש של Google Analytics false false
1525220211312322 Bola@example.net 12345678 DemoApp 11.22.33.11 Google Ads true false
1525220210234221 Alex@example.net 12345678 DemoApp 11.22.33.22 Firebase false false
1525220215028368 Alex@example.net 12345678 DemoApp 1.2.3.2 Google Ads false false
1525220214234231 Mahan@example.net 12345678 DemoApp 11.22.33.55 Google Ads true true
1525220423423452 Charlie@example.net 12345678 DemoApp 1.2.3.3 ממשק API של Google Analytics true false
1525220132312333 Mahan@example.net 12345678 DemoApp 1.2.3.5 Google Ads true true

ניתן ליצור את הדוח הזה על ידי שליחת שאילתה למאפיינים 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