名称： google-analytics
描述： |
集成 Google Analytics API 并管理 OAuth 认证。可管理账户、属性和数据流（Admin API），并运行关于会话、用户、页面浏览和转化的报告（Data API）。当用户需要配置或查询 Google Analytics 时使用此技能。对于其他第三方应用，请使用 api-gateway 技能 (https://clawhub.ai/byungkyu/api-gateway)。
compatibility: 需要网络访问权限和有效的 Maton API 密钥
元数据：
author: maton
version: "1.0"

Google Analytics

通过托管的 OAuth 认证访问 Google Analytics。此技能涵盖 Admin API（管理账户、属性、数据流）和 Data API（运行指标报告）。

快速开始

# 列出账户摘要 (Admin API)
curl -s -X GET "https://gateway.maton.ai/google-analytics-admin/v1beta/accountSummaries" -H "Authorization: Bearer $MATON_API_KEY"

# 运行报告 (Data API)
curl -s -X POST "https://gateway.maton.ai/google-analytics-data/v1beta/properties/{propertyId}:runReport" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}], "dimensions": [{"name": "city"}], "metrics": [{"name": "activeUsers"}]}'

基础 URL

Admin API (管理账户、属性、数据流)：

https://gateway.maton.ai/google-analytics-admin/{native-api-path}

Data API (运行报告)：

https://gateway.maton.ai/google-analytics-data/{native-api-path}

将 {native-api-path} 替换为实际的 Google Analytics API 端点路径。网关会将请求代理到 analyticsadmin.googleapis.com 和 analyticsdata.googleapis.com，并自动注入您的 OAuth 令牌。

认证

所有请求都需要在 Authorization 请求头中包含 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

环境变量： 将您的 API 密钥设置为 MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

1. 登录或在 maton.ai 创建账户。
2. 前往 maton.ai/settings。
3. 复制您的 API 密钥。

连接管理

在 https://ctrl.maton.ai 管理您的 Google OAuth 连接。

重要提示： Admin API 和 Data API 使用独立的连接：
- google-analytics-admin - 用于 Admin API 端点（管理账户、属性、数据流）
- google-analytics-data - 用于 Data API 端点（运行报告）

根据您要使用的 API 创建所需的连接。

列出连接

# 列出 Admin API 连接
curl -s -X GET "https://ctrl.maton.ai/connections?app=google-analytics-admin&status=ACTIVE" -H "Authorization: Bearer $MATON_API_KEY"

# 列出 Data API 连接
curl -s -X GET "https://ctrl.maton.ai/connections?app=google-analytics-data&status=ACTIVE" -H "Authorization: Bearer $MATON_API_KEY"

创建连接

# 创建 Admin API 连接（用于管理账户、属性、数据流）
curl -s -X POST "https://ctrl.maton.ai/connections" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"app": "google-analytics-admin"}'

# 创建 Data API 连接（用于运行报告）
curl -s -X POST "https://ctrl.maton.ai/connections" -H "Content-Type: application/json" -H "Authorization: Bearer $MATON_API_KEY" -d '{"app": "google-analytics-data"}'

获取连接详情

curl -s -X GET "https://ctrl.maton.ai/connections/{connection_id}" -H "Authorization: Bearer $MATON_API_KEY"

响应示例：

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "google-analytics-admin",
    "metadata": {}
  }
}

在浏览器中打开返回的 url 以完成 OAuth 授权。

删除连接

curl -s -X DELETE "https://ctrl.maton.ai/connections/{connection_id}" -H "Authorization: Bearer $MATON_API_KEY"

指定连接

如果您有多个 Google Analytics 连接，可以使用 Maton-Connection 请求头指定使用哪一个：

curl -s -X GET "https://gateway.maton.ai/google-analytics-admin/v1beta/accountSummaries" -H "Authorization: Bearer $MATON_API_KEY" -H "Maton-Connection: 21fd90f9-5935-43cd-b6c8-bde9d915ca80"

如果省略，网关将使用默认的（最早创建的）活跃连接。

Admin API 参考

账户

GET /google-analytics-admin/v1beta/accounts
GET /google-analytics-admin/v1beta/accounts/{accountId}
GET /google-analytics-admin/v1beta/accountSummaries

属性

GET /google-analytics-admin/v1beta/properties?filter=parent:accounts/{accountId}
GET /google-analytics-admin/v1beta/properties/{propertyId}

创建属性

POST /google-analytics-admin/v1beta/properties
Content-Type: application/json

{
  "parent": "accounts/{accountId}",
  "displayName": "我的新属性",
  "timeZone": "America/Los_Angeles",
  "currencyCode": "USD"
}

数据流

GET /google-analytics-admin/v1beta/properties/{propertyId}/dataStreams

创建网站数据流

POST /google-analytics-admin/v1beta/properties/{propertyId}/dataStreams
Content-Type: application/json

{
  "type": "WEB_DATA_STREAM",
  "displayName": "我的网站",
  "webStreamData": {"defaultUri": "https://example.com"}
}

自定义维度

GET /google-analytics-admin/v1beta/properties/{propertyId}/customDimensions

创建自定义维度

POST /google-analytics-admin/v1beta/properties/{propertyId}/customDimensions
Content-Type: application/json

{
  "parameterName": "user_type",
  "displayName": "用户类型",
  "scope": "USER"
}

转化事件

GET /google-analytics-admin/v1beta/properties/{propertyId}/conversionEvents
POST /google-analytics-admin/v1beta/properties/{propertyId}/conversionEvents

Data API 参考

运行报告

POST /google-analytics-data/v1beta/properties/{propertyId}:runReport
Content-Type: application/json

{
  "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
  "dimensions": [{"name": "city"}],
  "metrics": [{"name": "activeUsers"}]
}

运行实时报告

POST /google-analytics-data/v1beta/properties/{propertyId}:runRealtimeReport
Content-Type: application/json

{
  "dimensions": [{"name": "country"}],
  "metrics": [{"name": "activeUsers"}]
}

批量运行报告

POST /google-analytics-data/v1beta/properties/{propertyId}:batchRunReports
Content-Type: application/json

{
  "requests": [
    {
      "dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
      "dimensions": [{"name": "country"}],
      "metrics": [{"name": "sessions"}]
    }
  ]
}

获取元数据

GET /google-analytics-data/v1beta/properties/{propertyId}/metadata

常用报告示例

按页面统计的页面浏览量

{
  "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
  "dimensions": [{"name": "pagePath"}],
  "metrics": [{"name": "screenPageViews"}],
  "orderBys": [{"metric": {"metricName": "screenPageViews"}, "desc": true}],
  "limit": 10
}

按国家/地区统计的用户数

{
  "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
  "dimensions": [{"name": "country"}],
  "metrics": [{"name": "activeUsers"}, {"name": "sessions"}]
}

流量来源

{
  "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
  "dimensions": [{"name": "sessionSource"}, {"name": "sessionMedium"}],
  "metrics": [{"name": "sessions"}, {"name": "conversions"}]
}

常用维度

• date, country, city, deviceCategory
• pagePath, pageTitle, landingPage
• sessionSource, sessionMedium, sessionCampaignName

常用指标

• activeUsers, newUsers, sessions
• screenPageViews, bounceRate, averageSessionDuration
• conversions, eventCount

日期格式

• 相对日期：today, yesterday, 7daysAgo, 30daysAgo
• 绝对日期：2026-01-01

代码示例

JavaScript

// 列出账户摘要 (Admin API)
const accounts = await fetch(
  'https://gateway.maton.ai/google-analytics-admin/v1beta/accountSummaries',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);

// 运行报告 (Data API)
const report = await fetch(
  'https://gateway.maton.ai/google-analytics-data/v1beta/properties/123456:runReport',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    },
    body: JSON.stringify({
      dateRanges: [{ startDate: '30daysAgo', endDate: 'today' }],
      dimensions: [{ name: 'country' }],
      metrics: [{ name: 'activeUsers' }]
    })
  }
);

Python

import os
import requests

# 列出账户摘要 (Admin API)
accounts = requests.get(
    'https://gateway.maton.ai/google-analytics-admin/v1beta/accountSummaries',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)

# 运行报告 (Data API)
report = requests.post(
    'https://gateway.maton.ai/google-analytics-data/v1beta/properties/123456:runReport',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={
        'dateRanges': [{'startDate': '30daysAgo', 'endDate': 'today'}],
        'dimensions': [{'name': 'country'}],
        'metrics': [{'name': 'activeUsers'}]
    }
)

注意事项

• 仅支持 GA4 属性（不支持 Universal Analytics）。
• 属性 ID 为数字（例如 properties/521310447）。
• 使用 accountSummaries 可快速列出所有可访问的属性。
• 在 Admin API 的 PATCH 请求中使用 updateMask。
• 使用元数据端点来发现可用的维度和指标。
• 重要： 当 curl 命令的 URL 中包含方括号（如 fields[], sort[], records[]）时，请使用 curl -g 来禁用通配符解析。
• 重要： 当将 curl 输出通过管道传递给 jq 或其他命令时，在某些 shell 环境中，像 $MATON_API_KEY 这样的环境变量可能无法正确展开。在管道操作时，您可能会遇到 "Invalid API key" 错误。

错误处理

资源

• Admin API 概述
• 账户
• 属性
• 数据流
• Data API 概述
• 运行报告
• 实时报告