google-analytics-cli

Google Analytics CLI 技能

你可以使用 google-analytics-cli，这是一个只读的 GA4 API 命令行工具。用它运行报告、监控实时活动，以及探索账号和媒体资源结构。

快速开始

# Check if the CLI is available
google-analytics-cli --help

# List accounts and properties
google-analytics-cli accounts

如果尚未安装此命令行工具，请安装：

npm install -g google-analytics-cli

身份验证

此命令行工具使用 Google 服务账号凭据。凭据按以下顺序解析：

1. --credentials <path> 标志（针对单条命令）
2. --profile <name> 标志或 GA_PROFILE 环境变量 → ~/.config/google-analytics-cli/profiles/<name>.json
3. GOOGLE_APPLICATION_CREDENTIALS 环境变量
4. ~/.config/google-analytics-cli/credentials.json（自动检测）
5. gcloud 应用默认凭据

运行任何命令之前，请先运行 google-analytics-cli accounts 验证凭据。如果失败，请让用户设置服务账号，并在 Google Analytics 中授予其 Viewer 访问权限。

如果用户管理多个 GA 账号（例如多个客户或组织），请运行 google-analytics-cli profiles 列出可用的配置文件，然后传入 --profile <name>（例如 accounts --profile account-a）以指定目标账号。--credentials 和 --profile 不能同时使用；--credentials 的优先级高于 GA_PROFILE。

媒体资源 ID

大多数命令都需要 GA4 媒体资源 ID。可以通过以下方式提供：

• 位置参数：google-analytics-cli report 123456789 ...
• --property 标志：google-analytics-cli report --property 123456789 ...
• GA_PROPERTY_ID 环境变量：export GA_PROPERTY_ID=123456789

接受纯数字（123456789）和带前缀的格式（properties/123456789）。

输出格式

所有命令默认输出美化后的 JSON。使用 --format compact 输出单行 JSON。

管理命令

# List all accounts and their properties
google-analytics-cli accounts

# Get details about a specific property
google-analytics-cli property 123456789

# List properties for an account
google-analytics-cli properties 987654321
google-analytics-cli properties 987654321 --show-deleted

# List data streams for a property
google-analytics-cli data-streams 123456789

# List key events (conversions) for a property
google-analytics-cli key-events 123456789

# List custom dimensions for a property (Admin API)
google-analytics-cli admin-custom-dimensions 123456789

# List custom metrics for a property (Admin API)
google-analytics-cli admin-custom-metrics 123456789

# Get data retention settings for a property
google-analytics-cli data-retention 123456789

# List Google Ads links for a property
google-analytics-cli ads-links 123456789

# List annotations for a property (alpha API)
google-analytics-cli annotations 123456789

# Get custom dimensions and metrics for a property (Data API, filters by customDefinition)
google-analytics-cli custom-dims 123456789

# List configured credentials profiles (for users with multiple GA accounts)
google-analytics-cli profiles

更改历史记录

搜索账号的更改历史事件：

google-analytics-cli change-history 987654321
google-analytics-cli change-history 987654321 --filter-property 123456789
google-analytics-cli change-history 987654321 --earliest-change-time 2026-01-01T00:00:00Z
google-analytics-cli change-history 987654321 --earliest-change-time 2026-01-01T00:00:00Z --latest-change-time 2026-03-01T00:00:00Z
google-analytics-cli change-history 987654321 --actor-email [email protected]
google-analytics-cli change-history 987654321 --resource-type '["PROPERTY","DATA_STREAM"]'
google-analytics-cli change-history 987654321 --action '["CREATED","UPDATED"]'

访问报告

运行访问报告，查看谁访问过此媒体资源：

google-analytics-cli access-report 123456789 \
  --dimensions "accessorEmail,accessMechanism" \
  --metrics "accessCount" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]'

选项：--dimension-filter、--metric-filter、--order-by、--limit、--offset、--time-zone、--return-entity-quota、--include-all-users、--expand-groups。

注意：访问报告内部使用 dimensionName/metricName（而非 name）以及 entity（而非 property）。

运行报告

report 命令会运行 GA4 Data API 报告。

google-analytics-cli report <property_id> \
  --dimensions "<comma-separated>" \
  --metrics "<comma-separated>" \
  --date-ranges '<JSON array>' \
  [--dimension-filter '<JSON>'] \
  [--metric-filter '<JSON>'] \
  [--order-by '<JSON array>'] \
  [--limit <n>] \
  [--offset <n>] \
  [--currency-code <ISO4217>] \
  [--keep-empty-rows] \
  [--return-property-quota]

必需选项：--dimensions、--metrics、--date-ranges。

日期范围

--date-ranges 选项接受由日期范围对象组成的 JSON 数组：

# Relative dates
--date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]'

# Absolute dates
--date-ranges '[{"startDate": "2026-01-01", "endDate": "2026-01-31"}]'

# Compare two periods
--date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday", "name": "current"}, {"startDate": "60daysAgo", "endDate": "31daysAgo", "name": "previous"}]'

有效日期值：

• 绝对日期：YYYY-MM-DD（例如 2026-01-01）
• 相对日期：NdaysAgo（例如 30daysAgo、7daysAgo）
• 特殊值：yesterday、today
• 每个请求最多 4 个日期范围

维度筛选条件

--dimension-filter 选项接受 JSON FilterExpression：

# Exact match
--dimension-filter '{"filter": {"fieldName": "country", "stringFilter": {"matchType": "EXACT", "value": "United States"}}}'

# Contains
--dimension-filter '{"filter": {"fieldName": "pagePath", "stringFilter": {"matchType": "CONTAINS", "value": "/blog"}}}'

# Regex
--dimension-filter '{"filter": {"fieldName": "pagePath", "stringFilter": {"matchType": "PARTIAL_REGEXP", "value": "^/products/[0-9]+"}}}'

# In list
--dimension-filter '{"filter": {"fieldName": "eventName", "inListFilter": {"values": ["page_view", "scroll", "click"]}}}'

# AND group
--dimension-filter '{"andGroup": {"expressions": [{"filter": {"fieldName": "country", "stringFilter": {"matchType": "EXACT", "value": "United States"}}}, {"filter": {"fieldName": "deviceCategory", "stringFilter": {"matchType": "EXACT", "value": "mobile"}}}]}}'

# OR group
--dimension-filter '{"orGroup": {"expressions": [{"filter": {"fieldName": "country", "stringFilter": {"matchType": "EXACT", "value": "United States"}}}, {"filter": {"fieldName": "country", "stringFilter": {"matchType": "EXACT", "value": "Canada"}}}]}}'

# NOT
--dimension-filter '{"notExpression": {"filter": {"fieldName": "pagePath", "stringFilter": {"matchType": "EXACT", "value": "/"}}}}'

StringFilter 的 matchType 值：EXACT、BEGINS_WITH、ENDS_WITH、CONTAINS、FULL_REGEXP、PARTIAL_REGEXP。

指标筛选条件

--metric-filter 选项接受相同的 FilterExpression 结构，但使用数值筛选条件：

# Greater than
--metric-filter '{"filter": {"fieldName": "sessions", "numericFilter": {"operation": "GREATER_THAN", "value": {"int64Value": "100"}}}}'

# Between
--metric-filter '{"filter": {"fieldName": "bounceRate", "betweenFilter": {"fromValue": {"doubleValue": 0.5}, "toValue": {"doubleValue": 0.9}}}}'

NumericFilter 操作：EQUAL、LESS_THAN、LESS_THAN_OR_EQUAL、GREATER_THAN、GREATER_THAN_OR_EQUAL。

NumericValue：整数使用 {"int64Value": "string"}，小数使用 {"doubleValue": number}。

排序

--order-by 选项接受 JSON 数组：

# By metric descending
--order-by '[{"metric": {"metricName": "sessions"}, "desc": true}]'

# By dimension alphabetically
--order-by '[{"dimension": {"dimensionName": "date", "orderType": "ALPHANUMERIC"}}]'

# Multiple sort keys
--order-by '[{"metric": {"metricName": "sessions"}, "desc": true}, {"dimension": {"dimensionName": "country"}}]'

DimensionOrderBy 的 orderType 值：ALPHANUMERIC、CASE_INSENSITIVE_ALPHANUMERIC、NUMERIC。

透视报告

运行透视报告进行交叉表分析：

google-analytics-cli pivot-report 123456789 \
  --dimensions "country,browser" \
  --metrics "sessions,activeUsers" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --pivots '[{"fieldNames": ["browser"], "limit": 5, "orderBys": [{"metric": {"metricName": "sessions"}, "desc": true}]}]'

选项：--dimension-filter、--metric-filter、--currency-code、--keep-empty-rows、--return-property-quota。

批量报告

在单个请求中运行最多 5 份报告：

google-analytics-cli batch-report 123456789 \
  --requests '[{"dimensions": [{"name": "date"}], "metrics": [{"name": "activeUsers"}], "dateRanges": [{"startDate": "7daysAgo", "endDate": "yesterday"}]}, {"dimensions": [{"name": "country"}], "metrics": [{"name": "sessions"}], "dateRanges": [{"startDate": "7daysAgo", "endDate": "yesterday"}]}]'

元数据和兼容性

# Get full metadata (all available dimensions and metrics)
google-analytics-cli metadata 123456789

# Check if dimensions and metrics are compatible
google-analytics-cli check-compatibility 123456789 \
  --dimensions "date,country" \
  --metrics "sessions,activeUsers"

选项：--dimension-filter、--metric-filter（与 report 使用相同的 FilterExpression 格式）。

受众群体导出

# Create an audience export
google-analytics-cli audience-export-create 123456789 \
  --audience "properties/123456789/audiences/456" \
  --dimensions "deviceId,userId"

# Get status of an audience export
google-analytics-cli audience-export properties/123456789/audienceExports/789

# List all audience exports
google-analytics-cli audience-exports 123456789

# Query rows from a completed audience export
google-analytics-cli audience-export-query properties/123456789/audienceExports/789 \
  --limit 1000 --offset 0

实时报告

realtime 命令用于监控当前活动。无需日期范围或货币代码。

google-analytics-cli realtime <property_id> \
  --dimensions "<comma-separated>" \
  --metrics "<comma-separated>" \
  [--dimension-filter '<JSON>'] \
  [--metric-filter '<JSON>'] \
  [--order-by '<JSON array>'] \
  [--limit <n>] \
  [--return-property-quota]

实时报告涵盖最近 30 分钟的活动。

实时维度（有限集合）

appVersion、audienceId、audienceName、audienceResourceName、city、cityId、country、countryId、deviceCategory、eventName、minutesAgo、platform、streamId、streamName、unifiedScreenName

注意：当前分钟的 minutesAgo 为 "00"，前一分钟为 "01"，依此类推，最大为 "29"。

实时指标（仅 4 个）

activeUsers、eventCount、keyEvents、screenPageViews

常用维度参考

流量来源（会话范围）： sessionSource、sessionMedium、sessionSourceMedium、sessionDefaultChannelGroup、sessionCampaignName、sessionCampaignId

流量来源（首次用户获客）： firstUserSource、firstUserMedium、firstUserSourceMedium、firstUserDefaultChannelGroup、firstUserCampaignName

页面/屏幕： pagePath、pageTitle、pagePathPlusQueryString、landingPage、landingPagePlusQueryString、hostName、fullPageUrl、contentGroup

事件： eventName、isKeyEvent

用户： newVsReturning、userAgeBracket、userGender、firstSessionDate

地理位置： country、countryId、city、cityId、region、continent、language

设备： deviceCategory、browser、operatingSystem、operatingSystemVersion、screenResolution、mobileDeviceBranding、platform

时间： date、dateHour、day、dayOfWeek、dayOfWeekName、hour、month、week、year、yearMonth、nthDay

电子商务： transactionId、itemName、itemId、itemCategory、itemBrand、itemVariant、orderCoupon

Google Ads： sessionGoogleAdsCampaignName、sessionGoogleAdsAdGroupName、sessionGoogleAdsKeyword、sessionGoogleAdsAdNetworkType、googleAdsAccountName

受众群体： audienceId、audienceName

自定义维度： customEvent:parameter_name（事件范围）、customUser:parameter_name（用户范围）、customItem:parameter_name（商品范围）

常用指标参考

用户： activeUsers、newUsers、totalUsers

会话： sessions、sessionsPerUser、averageSessionDuration、bounceRate

互动： engagedSessions、engagementRate、screenPageViews、screenPageViewsPerSession、screenPageViewsPerUser、userEngagementDuration

事件： eventCount、eventCountPerUser、eventValue、eventsPerSession

关键事件（转化）： keyEvents、sessionKeyEventRate、userKeyEventRate

电子商务/收入： ecommercePurchases、purchaseRevenue、totalRevenue、transactions、averagePurchaseRevenue、averageRevenuePerUser、itemRevenue、addToCarts、checkouts、cartToViewRate

广告： advertiserAdClicks、advertiserAdCost、advertiserAdCostPerClick、advertiserAdImpressions、returnOnAdSpend

自定义指标： customEvent:parameter_name（总和）、averageCustomEvent:parameter_name（平均值）、countCustomEvent:parameter_name（计数）

报告示例

流量概览（最近 30 天）：

google-analytics-cli report 123456789 \
  --dimensions "sessionDefaultChannelGroup" \
  --metrics "sessions,activeUsers,engagementRate,keyEvents,totalRevenue" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "sessions"}, "desc": true}]'

按浏览量排列的热门页面：

google-analytics-cli report 123456789 \
  --dimensions "pagePath" \
  --metrics "screenPageViews,activeUsers,averageSessionDuration,bounceRate" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "screenPageViews"}, "desc": true}]' \
  --limit 20

每日趋势：

google-analytics-cli report 123456789 \
  --dimensions "date" \
  --metrics "activeUsers,sessions,screenPageViews,keyEvents" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"dimension": {"dimensionName": "date"}}]'

流量来源细分：

google-analytics-cli report 123456789 \
  --dimensions "sessionSource,sessionMedium" \
  --metrics "sessions,activeUsers,engagementRate,bounceRate,keyEvents" \
  --date-ranges '[{"startDate": "7daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "sessions"}, "desc": true}]' \
  --limit 20

着陆页表现：

google-analytics-cli report 123456789 \
  --dimensions "landingPage" \
  --metrics "sessions,activeUsers,bounceRate,keyEvents,averageSessionDuration" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "sessions"}, "desc": true}]' \
  --limit 20

设备细分：

google-analytics-cli report 123456789 \
  --dimensions "deviceCategory" \
  --metrics "activeUsers,sessions,engagementRate,bounceRate,screenPageViews" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]'

地理位置：

google-analytics-cli report 123456789 \
  --dimensions "country" \
  --metrics "activeUsers,sessions,engagementRate,keyEvents" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "activeUsers"}, "desc": true}]' \
  --limit 20

事件分析：

google-analytics-cli report 123456789 \
  --dimensions "eventName" \
  --metrics "eventCount,eventCountPerUser,eventValue" \
  --date-ranges '[{"startDate": "7daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "eventCount"}, "desc": true}]' \
  --limit 20

时段对比：

google-analytics-cli report 123456789 \
  --dimensions "sessionDefaultChannelGroup" \
  --metrics "sessions,activeUsers,keyEvents" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday", "name": "current"}, {"startDate": "60daysAgo", "endDate": "31daysAgo", "name": "previous"}]' \
  --order-by '[{"metric": {"metricName": "sessions"}, "desc": true}]'

电子商务表现：

google-analytics-cli report 123456789 \
  --dimensions "itemName" \
  --metrics "itemRevenue,itemsPurchased,addToCarts,cartToViewRate" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "itemRevenue"}, "desc": true}]' \
  --limit 20

新用户与回访用户：

google-analytics-cli report 123456789 \
  --dimensions "newVsReturning" \
  --metrics "activeUsers,sessions,engagementRate,screenPageViews,keyEvents" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]'

用户获客（首次触点）：

google-analytics-cli report 123456789 \
  --dimensions "firstUserDefaultChannelGroup" \
  --metrics "newUsers,activeUsers,sessions,keyEvents,totalRevenue" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "newUsers"}, "desc": true}]'

营销活动（UTM）表现：

google-analytics-cli report 123456789 \
  --dimensions "sessionCampaignName,sessionSourceMedium" \
  --metrics "sessions,activeUsers,engagementRate,keyEvents,totalRevenue" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "sessions"}, "desc": true}]' \
  --limit 20

Google Ads 营销活动表现：

google-analytics-cli report 123456789 \
  --dimensions "sessionGoogleAdsCampaignName" \
  --metrics "sessions,keyEvents,advertiserAdCost,advertiserAdClicks,returnOnAdSpend" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "advertiserAdCost"}, "desc": true}]'

筛选后的报告（仅限博客页面、美国移动用户）：

google-analytics-cli report 123456789 \
  --dimensions "pagePath" \
  --metrics "screenPageViews,activeUsers,engagementRate" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --dimension-filter '{"andGroup": {"expressions": [{"filter": {"fieldName": "pagePath", "stringFilter": {"matchType": "BEGINS_WITH", "value": "/blog"}}}, {"filter": {"fieldName": "country", "stringFilter": {"matchType": "EXACT", "value": "United States"}}}, {"filter": {"fieldName": "deviceCategory", "stringFilter": {"matchType": "EXACT", "value": "mobile"}}}]}}' \
  --order-by '[{"metric": {"metricName": "screenPageViews"}, "desc": true}]' \
  --limit 20

实时 -- 按国家/地区查看活跃用户：

google-analytics-cli realtime 123456789 \
  --dimensions "country" \
  --metrics "activeUsers" \
  --order-by '[{"metric": {"metricName": "activeUsers"}, "desc": true}]'

实时 -- 活跃页面：

google-analytics-cli realtime 123456789 \
  --dimensions "unifiedScreenName" \
  --metrics "activeUsers,screenPageViews" \
  --order-by '[{"metric": {"metricName": "activeUsers"}, "desc": true}]' \
  --limit 10

重要规则

1. 维度/指标兼容性。 并非所有维度和指标都可以一起使用。如果遇到兼容性错误，请减少维度数量或尝试不同的组合。运行报告前，请使用 check-compatibility 命令进行测试，或使用 metadata 查看所有可用的维度和指标。

2. 每个报告请求最多 9 个维度。

3. 每个报告请求最多 4 个日期范围。

4. 每次响应最多 250,000 行。使用 --offset 和 --limit 进行分页。

5. 实时数据受限。 仅支持 15 个维度和 4 个指标。不支持日期范围、货币代码和偏移量。数据涵盖最近 30 分钟。

6. 受阈值限制的维度。 当行数过少时，userAgeBracket、userGender 和 audienceId/audienceName 可能会返回经过阈值处理（抽样）的数据，以保护隐私。

7. 配额。 使用 --return-property-quota 检查当前配额状态。标准属性每天有 200,000 个令牌。

8. 筛选范围。 --dimension-filter 仅接受维度字段名称。--metric-filter 仅接受指标字段名称。API 会分别应用这两种筛选条件。

9. 批量报告。 每个批量请求最多包含 5 个报告对象。

10. 受众导出。 创建导出会返回一个长时间运行的操作。使用 audience-export 轮询，直到状态为 ACTIVE，然后使用 audience-export-query 查询行。

工作流指南

快速概览

1. 运行 google-analytics-cli accounts 查找属性
2. 使用 sessionDefaultChannelGroup 和关键指标运行流量概览报告
3. 按日期呈现趋势

深入分析

1. 从整体分析开始：流量渠道和顶层指标
2. 深入分析：找出表现不佳的特定页面、事件或来源
3. 对比不同时段以识别趋势
4. 检查设备和地理位置细分，找出特定细分群体的问题
5. 使用 --dimension-filter 隔离特定细分群体

探索属性

1. 运行 google-analytics-cli properties <account_id> 查看所有属性
2. 运行 google-analytics-cli data-streams <property_id> 查看数据流
3. 运行 google-analytics-cli key-events <property_id> 查看已配置的转化事件
4. 运行 google-analytics-cli metadata <property_id> 查看所有可用的维度和指标
5. 运行 google-analytics-cli check-compatibility <property_id>，再生成复杂报告

错误处理

• 权限被拒绝 -- 服务账号需要在 Google Analytics 中拥有 Viewer 访问权限
• 维度/指标不兼容 -- 使用 check-compatibility 进行测试，减少维度数量或尝试不同的组合
• 结果为空 -- 检查属性 ID、日期范围，以及这些维度是否存在数据
• 超出配额 -- 使用 --return-property-quota 检查用量；降低请求频率或复杂度

API 文档参考

• google-analytics-cli 文档
• GA4 Data API 概览
• 维度和指标参考
• Realtime API 架构
• FilterExpression 参考
• OrderBy 参考
• 配额和限制
• GA4 Admin API