資料存取報表 (original) (raw)

您可以使用 Admin API v1 runAccessReport 方法建立資料存取報表。這份報表會顯示每次使用者讀取 Google Analytics 資料的情形。資料存取記錄最多會保留 2 年。只有具備管理員角色的使用者，才能查看資料存取報表。

使用用戶端程式庫要求資料存取報表

如要開始使用資料存取報表，最快的方法就是使用用戶端程式庫。

如要瞭解如何安裝及設定 Google Analytics 用戶端程式庫，請參閱快速入門指南。

以下是使用 Python 用戶端程式庫的範例，該程式庫會執行資料存取查詢並顯示回應。

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}")

資料存取報表要求的語意與許多常見功能的核心報表要求相同。舉例來說，分頁、維度篩選器和日期範圍在兩種報表類型中都會以相同方式運作。

請先參閱 Data API v1 中核心報表的總覽，然後返回本頁面，進一步瞭解資料存取報表。

建立資料存取報表

使用 runAccessReport 方法要求資料存取報表。

選取報表實體

與 Data API v1 的核心報表功能類似，Google Analytics Admin API v1 的 runAccessReport 方法需要在網址要求路徑中以 properties/GA_PROPERTY_ID 的形式指定 Google Analytics 資源 ID，例如：

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

系統會根據指定 Google Analytics 資源的 Google Analytics 資料存取記錄，產生最終的資料存取報表。

如果您使用的是 Admin API 用戶端程式庫，就不需要手動操作要求網址路徑。大多數 API 用戶端都會提供 property 參數，該參數預期字串格式為 properties/GA_PROPERTY_ID。如需用戶端程式庫的使用範例，請參閱本頁開頭的程式碼片段。

選擇維度和指標

維度可描述及分組資源的存取資料。舉例來說，維度 userEmail 會指出存取報表資料的使用者電子郵件地址。報表回應中的維度值為字串。

指標代表報表的量化評估資料，accessCount 指標會傳回資料存取記錄的總數。

如要查看資料存取報表要求中可用的維度和指標名稱完整清單，請參閱「資料存取架構」。

索取報表

如要要求資料存取報表，請建構 RunAccessReportRequest 物件。建議您先從下列要求參數開始：

• 日期範圍欄位中至少有一個有效的項目。
• dimensions 欄位中至少有一個有效的項目。
• 如果不使用 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"
    }
  ]
}

閱讀回應

資料存取報表回應主要包含標頭和資料列。標頭包含 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
}

依存取記錄篩選

使用 RunAccessReportRequest 物件的 dimensionFilter 欄位，將報表回應限制為符合篩選器的特定維度值。

以下範例會根據個別資料存取記錄產生報表，並篩選電子郵件為 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"
      }
    }
  }
}

同樣地，RunAccessReportRequest 物件的 metricFilter 欄位可用來限制報表回應，只顯示符合篩選器的特定指標值。

以下範例會產生報表，其中包含電子郵件和存取次數，這些資料來自存取指定資源超過 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 建立的範例存取報表：

您可以查詢維度 mostRecentAccessEpochTimeMicros、userEmail 和 accessCount 指標來產生這份報表。這份報表會為每位使用者提供一列資料：mostRecentAccessEpochTimeMicros 維度會匯總每位存取資源的使用者資料存取記錄，並傳回每個資料列的上次存取時間 (以 Unix 微秒自紀元開始計算)。

使用者存取權細目

另一個實用的報表範例，是依據存取機制 (例如 Google Analytics 使用者介面、API 等) 細分使用者存取情況。

您可以查詢維度 mostRecentAccessEpochTimeMicros、userEmail、accessMechanism 和 accessCount 指標，產生這份報表。

報表中會列出每個使用者/存取機制組合的資料列。mostRecentAccessEpochTimeMicros 維度包含使用者上次使用指定存取機制存取資源的時間。

資源存取權總覽

您可以為資源產生報表，而不需要細分個別使用者。舉例來說，下列報表會說明使用不同存取機制存取資源的頻率：

您可以查詢維度 accessedPropertyId、accessedPropertyName、accessMechanism 和 accessCount 指標，產生這份報表。

報表中每個資源 ID/存取機制組合都會包含一列。

個人資料存取權

如要產生每個資料列皆根據個別資料存取記錄的報表，請在查詢中省略 mostRecentAccessEpochTimeMicros 維度，改用 epochTimeMicros 維度。由於報表的每列都包含單一資料存取事件的相關資訊，因此您不必查詢 accessCount 指標。

下列報表包含使用者每次存取指定資源的詳細資訊。

您可以查詢維度 epochTimeMicros、userEmail、accessedPropertyId、accessedPropertyName、userIP、accessMechanism、costDataReturned、revenueDataReturned，產生這份報表。