mcpField
G
google-analytics-data-api-basics

google-analytics-data-api-basics

github.com/google数据与数据库21.6k7.6k 次安装今天更新
代码仓库

关于 google-analytics-data-api-basics

该技能介绍 Google Analytics Data API v1beta 的启用、认证和报告查询，面向需要在程序中读取分析数据的开发者。它提供多种语言客户端库的入门指引，并说明指标与维度兼容性检查。

主要功能

  1. 01启用 Data API 并配置 ADC
  2. 02多语言客户端库入门指引
  3. 03创建分析报告请求
  4. 04查询常用指标与维度
  5. 05检查字段组合兼容性

适用场景

  1. 01按日期和城市生成活跃用户报告
  2. 02将 Analytics 数据接入应用
  3. 03构建自定义分析仪表板
  4. 04运行自动化报告工作流

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/google/skills --skill google-analytics-data-api-basics

安装后在 Claude Code 中输入/google-analytics-data-api-basics确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
dotnet.md
go.md
java.md
nodejs.md
php.md
python.md
ruby.md

详细介绍

开始使用 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），并为账号授予必要的作用域。在终端中运行以下 命令：

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 客户端库。 请始终优先使用 API 的 v1beta 版本，以获得稳定性并访问 当前的 Google Analytics 报告功能。

重要

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 客户端库， 请阅读设置指南：

  • Go 安装参考 （包： cloud.google.com/go/analytics/data/apiv1beta）
.NET

如果需要安装或设置 .NET / C# 的 Google Analytics Data API 客户端库， 请阅读设置指南：

Ruby

如果需要安装或设置 Ruby 的 Google Analytics Data API 客户端库， 请阅读设置指南：

说明

其他资源：如需查看通过 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 端点兼容，并对请求进行强类型验证。

指标和维度架构

构建 RunReportRequest 时，必须使用有效的 API 维度和指标名称。完整且权威的可用字段列表，请参阅官方的 Data API 架构文档。

常用维度

维度表示数据的类别属性。

  • city：用户所在的城镇或城市。
  • country：用户所在的国家/地区。
  • date：事件日期，格式为 YYYYMMDD。
  • deviceCategory：移动设备的类别（例如，桌面设备、手机、 平板电脑）。
  • eventName：触发的事件名称。
  • pageTitle：网页标题。
常用指标

指标表示定量测量值。

  • activeUsers：活跃用户数。
  • eventCount：事件总数。
  • sessions：会话总数。
  • screenPageViews：浏览的应用屏幕数或网页数。
  • totalRevenue：购买、订阅和广告带来的总收入。
指标和维度兼容性检查

有些维度和指标无法在同一个报告请求中一起查询。如果遇到与字段不兼容相关的 INVALID_ARGUMENT 错误，请检查字段组合。要以编程方式访问 Data API 架构，请使用 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")

评论

支持 Markdown