Google-analytics-GA4 — GA4分析查询

Name: Google-analytics-GA4 — GA4分析查询
Rating: 1 (1 reviews)
Author: whao

whao

Google-analytics-GA4 — GA4分析查询

v1.0.0

通过官方Data API查询Google Analytics GA4属性的实时和历史用户指标、维度和元数据。支持实时活跃用户查询、历史报表生成、维度与指标元数据发现等功能。

1· 122·0 当前·0 累计

by @whosc (whao)·MIT-0

数据与API 数据分析

下载技能包

License

MIT-0

最后更新

2026/3/20

安全扫描

VirusTotal

无害

查看报告

OpenClaw

安全

high confidence

该技能的代码、指令和环境需求与其通过官方Data API查询GA4的声明目的一致；该包中没有任何内容请求无关凭据或访问未知端点。

评估建议

这似乎是一个合法的GA4报告技能。安装前：(1)不要将真实的服务账户JSON密钥提交到仓库，使用Viewer限制的服务账户；(2)检查技能目录中是否存在包含密钥的意外ga-credentials.json（仓库包含一个空的ga-credentials.json占位符）；(3)注意某些脚本将GOOGLE_APPLICATION_CREDENTIALS设置为本地ga-credentials.json，这可能会覆盖您的全局设置——如果您更喜欢不同的路径，请删除或编辑该行；(4)只有在需要传出通知时才设置DINGTALK_WEBHOOK/DINGTALK_SECRET；以及(5)首先查看并运行test_connection.py以确认权限和配额，然后再进行大规模导出。...

详细分析 ▾

✓ 用途与能力

名称/描述（GA4报告）与包含的文件（CLI、辅助函数、测试、可选报表）相匹配。所需依赖（google-analytics-data，可选的requests）符合功能要求。

ℹ 指令范围

SKILL.md和代码将操作限制在创建/使用Google服务账户JSON密钥、调用GA4 Data API，以及在用户配置webhook环境变量时可选发送通知（DingTalk）。一个小惊喜：几个脚本无条件地将GOOGLE_APPLICATION_CREDENTIALS设置为./ga-credentials.json，这可能会覆盖现有的环境变量——文档提到了两种选项，但脚本行为可能出乎某些用户的意料。

✓ 安装机制

无自动安装/下载或远程安装程序；依赖项是requirements.txt中列出的标准Python包。该包以源文件形式分发（无隐蔽的外部负载）。

ℹ 凭证需求

该技能不请求无关的密钥。它期望一个Google服务账户JSON（GOOGLE_APPLICATION_CREDENTIALS或ga-credentials.json），并可能使用GA4_PROPERTY_ID或config.json进行属性选择。可选的DingTalk webhook环境变量已记录——这些是合理的，但与GA4数据访问无关，只有在您打算使用通知时才应设置。

✓ 持久化与权限

该技能不是强制包含的（always:false），也不会修改其他技能或全局代理配置。它按需运行，没有提升的平台权限。

安全有层次，运行前请审查代码。

License

MIT-0

可自由使用、修改和再分发，无需署名。

查看条款 ↗

运行时依赖

无特殊依赖

版本

latestv1.0.02026/3/20

从命令行调用Google Analytics API读取GA4数据（非Universal Analytics）。

● 无害

安装命令点击复制

官方npx clawhub@latest install google-analytics-ga4

镜像加速npx clawhub@latest install google-analytics-ga4 --registry https://cn.clawhub-mirror.com

技能文档

使用 Google Analytics Data API v1 查询GA4属性。

功能

实时指标 — 例如过去N分钟的活跃用户
历史报表 — 自定义日期范围、指标、维度、分页
元数据 — 发现有效的维度和指标API名称
属性列表提示 — Data API本身无法枚举属性；文档说明在哪里找到数字ID

设置

1. 创建服务账户

打开 Google Cloud Console。
创建或选择项目。
启用 Google Analytics Data API。
创建服务账户：IAM & Admin → Service Accounts → Create service account。

- 可选GCP角色：BigQuery Job User（仅当您也使用BigQuery时）。

完成向导。

2. 创建JSON密钥

打开服务账户 → Keys。
Add key → Create new key → JSON。
下载文件并保存为ga-credentials.json（或通过--credentials/GOOGLE_APPLICATION_CREDENTIALS传递的任何路径）。

3. 授予GA4访问权限

打开 Google Analytics。
选择属性。
Admin（齿轮）→ Property access management。
Add users → 输入服务账户邮箱（…@….iam.gserviceaccount.com）。
角色：至少 Viewer。

4. 凭据位置

任选其一：

A. 将ga-credentials.json放在此技能目录中，或
B. 将GOOGLE_APPLICATION_CREDENTIALS设置为JSON密钥的绝对路径。

切勿提交真实密钥。.gitignore排除ga-credentials.json和config.json。

示例

属性列表指导

python ga_query.py --action list-properties

实时（活跃用户）

python ga_query.py --action realtime \
  --property-id YOUR-GA4-PROPERTY-ID

历史数据

python ga_query.py --action historical \
  --property-id YOUR-GA4-PROPERTY-ID \
  --start-date 7daysAgo \
  --end-date yesterday \
  --metrics activeUsers,sessions,eventCount \
  --dimensions country,deviceCategory

元数据

python ga_query.py --action metadata \
  --property-id YOUR-GA4-PROPERTY-ID

参数

通用参数

参数	描述	默认值
`--property-id`	数字GA4属性ID	除`list-properties`外必填
`--credentials`	服务账户JSON路径	`ga-credentials.json`

实时参数

参数	描述	默认值
`--metrics`	逗号分隔的指标	`activeUsers`
`--dimensions`	逗号分隔的维度	（无）
`--minute-range`	分钟前窗口，例如`0-30`	`0-30`

历史参数

参数	描述	默认值
`--start-date`	开始（`YYYY-MM-DD`或相对值）	必填
`--end-date`	结束	必填
`--metrics`	逗号分隔的指标	`activeUsers`
`--dimensions`	逗号分隔的维度	（无）
`--limit`	最大行数	`10000`
`--offset`	分页偏移	`0`

常用指标

名称	含义
`activeUsers`	活跃用户
`sessions`	会话数
`eventCount`	事件数
`engagementRate`	参与率
`averageSessionDuration`	平均会话时长（秒）
`screenPageViews`	页面/屏幕浏览量
`conversions`	转化数
`totalRevenue`	收入

常用维度

名称	含义
`country`	国家
`city`	城市
`deviceCategory`	桌面/移动/平板
`eventName`	事件名称
`pagePath`	页面路径
`source`	流量来源
`medium`	媒介
`campaign`	广告系列
`date`	日期

日期表达式

绝对值：2024-01-15
相对值：today、yesterday、7daysAgo、30daysAgo

输出

默认：Markdown表格。使用--output json获取机器可读输出。

依赖

pip install google-analytics-data

可选（流量来源报表+DingTalk）：pip install requests并设置DINGTALK_WEBHOOK/DINGTALK_SECRET。

参考资料

Query GA4 properties using the Google Analytics Data API v1.

Capabilities

Realtime metrics — e.g. active users in the last N minutes
Historical reports — custom date ranges, metrics, dimensions, paging
Metadata — discover valid dimension and metric API names
Property list hint — Data API alone cannot enumerate properties; doc explains where to find the numeric ID

Setup

1. Create a service account

Open Google Cloud Console.
Create or select a project.
Enable Google Analytics Data API.
Create a service account: IAM & Admin → Service Accounts → Create service account.

- Optional GCP role: BigQuery Job User (only if you also use BigQuery).

Finish the wizard.

2. Create a JSON key

Open the service account → Keys.
Add key → Create new key → JSON.
Download the file and save it as ga-credentials.json (or any path you pass via --credentials / GOOGLE_APPLICATION_CREDENTIALS).

3. Grant GA4 access

Open Google Analytics.
Select the property.
Admin (gear) → Property access management.
Add users → enter the service account email (…@….iam.gserviceaccount.com).
Role: at least Viewer.

4. Credentials location

Either:

A. Place ga-credentials.json in this skill directory, or
B. Set GOOGLE_APPLICATION_CREDENTIALS to the absolute path of the JSON key.

Never commit real keys. .gitignore excludes ga-credentials.json and config.json.

Examples

Property list guidance

python ga_query.py --action list-properties

Realtime (active users)

python ga_query.py --action realtime \
  --property-id YOUR-GA4-PROPERTY-ID

Historical

python ga_query.py --action historical \
  --property-id YOUR-GA4-PROPERTY-ID \
  --start-date 7daysAgo \
  --end-date yesterday \
  --metrics activeUsers,sessions,eventCount \
  --dimensions country,deviceCategory

Metadata

python ga_query.py --action metadata \
  --property-id YOUR-GA4-PROPERTY-ID

Arguments

Common

Argument	Description	Default
`--property-id`	Numeric GA4 property ID	Required (except `list-properties`)
`--credentials`	Service account JSON path	`ga-credentials.json`

Realtime

Argument	Description	Default
`--metrics`	Comma-separated metrics	`activeUsers`
`--dimensions`	Comma-separated dimensions	(none)
`--minute-range`	Minutes ago window, e.g. `0-30`	`0-30`

Historical

Argument	Description	Default
`--start-date`	Start (`YYYY-MM-DD` or relative)	Required
`--end-date`	End	Required
`--metrics`	Comma-separated metrics	`activeUsers`
`--dimensions`	Comma-separated dimensions	(none)
`--limit`	Max rows	`10000`
`--offset`	Paging offset	`0`

Common metrics

Name	Meaning
`activeUsers`	Active users
`sessions`	Sessions
`eventCount`	Event count
`engagementRate`	Engagement rate
`averageSessionDuration`	Avg session duration (seconds)
`screenPageViews`	Page / screen views
`conversions`	Conversions
`totalRevenue`	Revenue

Common dimensions

Name	Meaning
`country`	Country
`city`	City
`deviceCategory`	desktop / mobile / tablet
`eventName`	Event name
`pagePath`	Page path
`source`	Traffic source
`medium`	Medium
`campaign`	Campaign
`date`	Date

Date expressions

Absolute: 2024-01-15
Relative: today, yesterday, 7daysAgo, 30daysAgo

Output

Default: Markdown tables. Use --output json for machine-readable output.

Dependencies

pip install google-analytics-data

Optional (traffic source report + DingTalk): pip install requests and set DINGTALK_WEBHOOK / DINGTALK_SECRET.

References

数据来源：ClawHub ↗ · 中文优化：龙虾技能库

OpenClaw 技能定制 / 插件定制 / 私有工作流定制

免费技能或插件可能存在安全风险，如需更匹配、更安全的方案，建议联系付费定制

了解定制服务

License

运行时依赖

版本

安装命令 点击复制

技能文档

功能

设置

1. 创建服务账户

2. 创建JSON密钥

3. 授予GA4访问权限

4. 凭据位置

示例

属性列表指导

实时（活跃用户）

历史数据

元数据

参数

通用参数

实时参数

历史参数

常用指标

常用维度

日期表达式

输出

依赖

参考资料

Capabilities

Setup

1. Create a service account

2. Create a JSON key

3. Grant GA4 access

4. Credentials location

Examples

Property list guidance

Realtime (active users)

Historical

Metadata

Arguments

Common

Realtime

Historical

Common metrics

Common dimensions

Date expressions

Output

Dependencies

References

安装命令点击复制