AI Skills
google-analytics-data-api-basics

google-analytics-data-api-basics

熱門

管理 Google Analytics 報表資料、透過 Cloud CLI 啟用 Analytics Data API，並使用 Google Analytics Data API (v1beta) 建立報表。當您需要與 Google Analytics 資源互動、執行自訂分析報表、查詢指標（如 activeUsers、screenPageViews）與維度（如 city、date）、檢查指標與維度的相容性，或驗證 API 是否已啟用時使用。請勿用於 Google Analytics Admin API 操作（例如建立資源、管理使用者）或前端追蹤程式碼的安裝。

1.6萬星標
1242分支
更新於 2026/8/6
獲取技能源代碼

相關技能

fal-ai-media24萬flox-environments24萬cloud11萬
SKILL.md
唯讀
名稱
google-analytics-data-api-basics
描述

管理 Google Analytics 報表資料、透過 Cloud CLI 啟用 Analytics Data API，並使用 Google Analytics Data API (v1beta) 建立報表。當您需要與 Google Analytics 資源互動、執行自訂分析報表、查詢指標（如 activeUsers、screenPageViews）與維度（如 city、date）、檢查指標與維度的相容性，或驗證 API 是否已啟用時使用。請勿用於 Google Analytics Admin API 操作（例如建立資源、管理使用者）或前端追蹤程式碼的安裝。

Google Analytics Data API 入門指南

Google Analytics Data API v1beta 提供以程式碼存取 Google Analytics 報表資料的功能。您可以透過它建立自訂儀表板、將報表工作流程自動化，並將 Google Analytics 資料整合至企業級應用程式中。

透過 Cloud CLI 啟用 API

在呼叫 API 之前，請先確認 Google Cloud 專案中已啟用 Google Analytics Data API。

若系統找不到 gcloud，請提示使用者在執行下列指令前先安裝 Google Cloud CLI。

  1. 啟用 API： 使用 Cloud CLI (gcloud) 來啟用 analyticsdata.googleapis.com。

    gcloud services enable analyticsdata.googleapis.com --quiet

    原因：啟用 API 可確保您的 Cloud 專案已獲得執行 Google Analytics 報表所需的配額與權限。

  2. 驗證 API 是否已啟用：

    gcloud services list --enabled --filter="analyticsdata.googleapis.com"

身分驗證

若要驗證 API 要求的身分，您必須產生應用程式預設憑證（Application Default Credentials，簡稱 ADC），並為帳戶授予所需的存取範圍（scopes）。請在終端機執行以下指令：

gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly"

原因：這會在您的本機環境中設定 ADC，並包含必要的 Cloud Platform 與 Google Analytics 唯讀存取範圍，讓用戶端函式庫能自動驗證您的要求。

建立 Data API 報表 (v1beta)

若要建立報表，請使用官方的 Google Analytics Data 用戶端函式庫。為確保穩定度並取得最新的 Google Analytics 報表功能，請優先選擇 API 的 v1beta 版本。

[!IMPORTANT] Agent 強制指令： 當使用者選擇或需要特定的程式語言時，請閱讀下方 references/ 目錄中對應的用戶端函式庫設定參考指南。

支援的用戶端函式庫

Python

若您需要安裝或設定 Python 的 Google Analytics Data API 用戶端函式庫，請閱讀設定指南：

Java

若您需要安裝或設定 Java 的 Google Analytics Data API 用戶端函式庫，請閱讀設定指南：

PHP

若您需要安裝或設定 PHP 的 Google Analytics Data API 用戶端函式庫，請閱讀設定指南：

Node.js

若您需要安裝或設定 Node.js 的 Google Analytics Data API 用戶端函式庫，請閱讀設定指南：

Go

若您需要安裝或設定 Go 的 Google Analytics Data API 用戶端函式庫，請閱讀設定指南：

.NET

若您需要安裝或設定 .NET / C# 的 Google Analytics Data API 用戶端函式庫，請閱讀設定指南：

Ruby

若您需要安裝或設定 Ruby 的 Google Analytics Data API 用戶端函式庫，請閱讀設定指南：

[!NOTE] 其他資源：如需更多關於使用 Java、PHP、Node.js、.NET、Python 和 REST 呼叫 Data API 的範例，以及服務帳戶身分驗證的技巧，請參閱官方的 Data API 快速入門。

Python 快速入門

  1. 安裝用戶端函式庫：

    pip install google-analytics-data

    若系統未安裝 pip，請提示使用者在安裝用戶端函式庫之前先安裝 pip。

  2. 執行報表查詢： 以下完整範例示範如何查詢特定 Google Analytics 資源的活躍使用者數與工作階段數，並按城市與日期進行分組。請將 YOUR-PROPERTY-ID 替換為您實際的 Google Analytics 資源 ID（例如：1234567）。

    from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import DateRange, Dimension, Metric, RunReportRequest

def sample_run_report(property_id: str):
    # Initialize the client.
    # Assumes Application Default Credentials (ADC) are configured in your environment.
    client = BetaAnalyticsDataClient()

    request = RunReportRequest(
        property=f"properties/{property_id}",
        dimensions=[
            Dimension(name="city"),
            Dimension(name="date")
        ],
        metrics=[
            Metric(name="activeUsers"),
            Metric(name="sessions")
        ],
        date_ranges=[
            DateRange(start_date="2026-05-01", end_date="today")
        ],
    )

    response = client.run_report(request)

    print(f"Report result for property {property_id}:")
    for row in response.rows:
        print(
            f"City: {row.dimension_values[0].value}, "
            f"Date: {row.dimension_values[1].value}, "
            f"Active Users: {row.metric_values[0].value}, "
            f"Sessions: {row.metric_values[1].value}"
        )

if __name__ == "__main__":
    sample_run_report("YOUR-PROPERTY-ID")

    原因：使用 BetaAnalyticsDataClient 與 RunReportRequest 可確保與 v1beta 端點的相容性，並具備強型別的要求驗證。

指標與維度架構（Schema）

建立 RunReportRequest 時，您必須使用有效的 API 維度與指標名稱。請參閱官方 Data API Schema 文件 取得完整的權威欄位清單。

常用維度

維度代表您資料中的類別屬性。

  • city: 使用者所在城鎮或城市。
  • country: 使用者所在國家/地區。
  • date: 事件發生的日期，格式為 YYYYMMDD。
  • deviceCategory: 行動裝置類別（例如：desktop、mobile、tablet）。
  • eventName: 觸發的事件名稱。
  • pageTitle: 網頁標題。

常用指標

指標代表定量測量值。

  • activeUsers: 活躍使用者人數。
  • eventCount: 事件總次數。
  • sessions: 工作階段總數。
  • screenPageViews: 應用程式畫面或網頁瀏覽次數。
  • totalRevenue: 包含購物、訂閱與廣告的總收益。

指標與維度相容性檢查

某些維度與指標無法在同一次報表要求中同時查詢。若您收到與不相容欄位相關的 INVALID_ARGUMENT 錯誤，請檢查您的欄位組合。若要透過程式碼存取 Data API schema，請使用 getMetadata()。若要在執行報表前透過程式碼檢查特定維度與指標組合的相容性，請使用 checkCompatibility() 方法。

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import CheckCompatibilityRequest, Compatibility, Dimension, Metric

def sample_check_compatibility(property_id: str):
    client = BetaAnalyticsDataClient()

    # Define the dimensions and metrics you want to query together.
    # For example, checking if 'itemName' (an e-commerce dimension)
    # is compatible with 'activeUsers' and 'totalRevenue'.
    request = CheckCompatibilityRequest(
        property=f"properties/{property_id}",
        dimensions=[
            Dimension(name="itemName"),
            Dimension(name="date")
        ],
        metrics=[
            Metric(name="activeUsers"),
            Metric(name="totalRevenue")
        ],
    )
    response = client.check_compatibility(request)

    print(f"Compatibility check for property {property_id}:")
    for dim in response.dimension_compatibilities:
        is_compatible = dim.compatibility == Compatibility.COMPATIBLE
        print(f"Dimension '{dim.dimension_metadata.api_name}' is compatible: {is_compatible}")

    for metric in response.metric_compatibilities:
        is_compatible = metric.compatibility == Compatibility.COMPATIBLE
        print(f"Metric '{metric.metric_metadata.api_name}' is compatible: {is_compatible}")

if __name__ == "__main__":
    sample_check_compatibility("YOUR-PROPERTY-ID")