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万Star
1242Fork
更新于 2026/8/6
获取 Skill源代码

相关 Skills

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 报表数据的能力。借助该 API，你可以构建自定义数据大屏/仪表盘、自动化报表工作流，并将 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"

原因：这会在本地环境中配置具有所需 Cloud Platform 及 Google Analytics 只读权限的 ADC，使客户端库能够自动完成后续请求的身份验证。

创建 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 的更多示例，以及使用服务账号（Service Account）进行身份验证的技巧，请参考官方 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")