Google Analytics技能使用说明

2026-03-27 新闻来源：网淘吧围观:33

电脑广告

手机广告

Google Analytics

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

快速开始

# 列出账户摘要（管理API）
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-analytics-admin/v1beta/accountSummaries')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

# 运行报告（数据API）
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'dateRanges': [{'startDate': '30daysAgo', 'endDate': 'today'}], 'dimensions': [{'name': 'city'}], 'metrics': [{'name': 'activeUsers'}]}).encode()
req = urllib.request.Request('https://gateway.maton.ai/google-analytics-data/v1beta/properties/{propertyId}:runReport', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础URL

管理API（管理账户、资源、数据流）：

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

数据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密钥

登录或在maton.ai
创建账户前往
maton.ai/settings

复制您的API密钥

连接管理在https://ctrl.maton.ai

管理您的Google OAuth连接管理API和数据API使用独立的连接：

google-analytics-admin- 管理API端点（管理账户、媒体资源、数据流）所必需
google-analytics-data- 数据API端点（运行报告）所必需

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

列出连接

# 列出管理API连接
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-analytics-admin&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

# 列出数据API连接
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-analytics-data&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

# 创建管理API连接（用于管理账户、媒体资源、数据流）
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'google-analytics-admin'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

# 创建数据API连接（用于运行报告）
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'google-analytics-data'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "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授权。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果您有多个 Google Analytics 连接，请使用Maton-Connection请求头指定要使用的连接：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-analytics-admin/v1beta/accountSummaries')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

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

管理 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

数据 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"}]
}

常用维度

日期,国家,城市,设备类别
页面路径,页面标题,着陆页
会话来源,会话媒介,会话活动名称

常用指标

活跃用户,新用户,会话次数
屏幕浏览量,跳出率,平均会话时长
转化次数,事件计数

日期格式

相对日期：今天,昨天,七天前,三十天前
绝对日期：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这样的环境变量可能无法正确展开。通过管道传递时，可能会出现“无效API密钥”的错误。错误处理

状态码

含义	400
缺少Google Analytics连接	401
Maton API密钥无效或缺失	429
请求频率受限（每个账户每秒10次请求）	4xx/5xx
来自Google Analytics API的透传错误	Passthrough error from Google Analytics API

故障排除：API密钥无效

当您收到“API密钥无效”错误时，在断定存在问题之前，请始终按照以下步骤操作：

检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

通过列出连接来验证API密钥是否有效：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排除：应用名称无效

确保您的URL路径以正确的应用名称开头：
- 对于Admin API：使用google-analytics-admin
- 对于Data API：使用google-analytics-data

示例：

正确：https://gateway.maton.ai/google-analytics-admin/v1beta/accountSummaries
正确：https://gateway.maton.ai/google-analytics-data/v1beta/properties/123456:runReport
不正确：https://gateway.maton.ai/analytics/v1beta/accountSummaries

资源

天猫隐藏优惠券

网淘吧

免责申明

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。

打赏

文章底部电脑广告

手机广告位-内容正文底部

标签

上一篇：Simmer技能使用说明下一篇：gogcli - Google Workspace CLI技能使用说明