gplay-reports-download

Google Play 报告下载

如果你需要从 Google Play Console 列出或下载财务报告（收入、销售额、付款）或统计报告（安装量、评分、崩溃、商店表现、订阅），请使用此技能。

报告的工作方式

Google Play Console 报告无法通过 REST API 获取。这些报告以 CSV/ZIP 文件的形式存储在 Google Cloud Storage（GCS）存储桶中：

• 存储桶名称：因账号而异，格式为 pubsite_prod_rev_<id> 或 pubsite_prod_<id>。请始终从 Play Console 复制准确的 URI。
• 财务报告：earnings/、sales/、payouts/、play_balance_krw/、wht_statements/ 前缀
• 统计报告：stats/installs/、stats/ratings/、stats/crashes/、stats/store_performance/、financial-stats/subscriptions/ 前缀

服务账号必须有权访问 GCS 存储桶（将服务账号添加到 Play Console 并授予相应权限后，会自动授予此访问权限）。

前提条件

• 通过 gplay auth login 配置的服务账号
• GCS 存储桶 ID（见下文——这不同于 Play Console URL 中的开发者 ID）
• 财务报告：VIEW_FINANCIAL_DATA 权限（必须将服务账号添加到 Play Console，并授予“查看财务数据”访问权限）
• 统计报告：VIEW_APP_INFORMATION 权限（必须将服务账号添加到 Play Console，并授予“查看应用信息”访问权限）

查找存储桶 ID

重要提示： 报告的存储桶 ID不是 Play Console URL 中的数字 ID。URL ID 与 GCS 存储桶 ID 不同。

查找正确的存储桶 ID：

1. 前往 Google Play Console > 下载报告（在左侧边栏的“下载报告”下）
2. 查找该页面上显示的 Cloud Storage URI，例如：

   gs://pubsite_prod_rev_12110000881713004121/
   

3. 可以传入完整 URI，也可以只传数字 ID：12110000881713004121

也可以使用 Google Cloud Console 查找与 Play Console 账号关联的存储桶名称。

常见错误： 使用 Play Console URL 中的开发者 ID（https://play.google.com/console/developers/<this_id>/...）会导致 404 Not Found 错误，因为 GCS 存储桶使用的是不同的内部 ID。

财务报告

列出可用的财务报告

# List all financial reports
gplay reports financial list --bucket-id <id>

# You can also pass the full GCS URI
gplay reports financial list --bucket-id "gs://pubsite_prod_rev_12345/"

# Filter by type
gplay reports financial list --bucket-id <id> --type earnings
gplay reports financial list --bucket-id <id> --type sales
gplay reports financial list --bucket-id <id> --type payouts

# Filter by date range
gplay reports financial list --bucket-id <id> --from 2026-01 --to 2026-06

# Combine filters
gplay reports financial list --bucket-id <id> --type earnings --from 2026-01 --to 2026-03

下载财务报告

# Download earnings for a specific month
gplay reports financial download --bucket-id <id> --from 2026-01 --type earnings

# Download to a specific directory
gplay reports financial download --bucket-id <id> --from 2026-01 --type earnings --dir ./reports

# Download a range of months
gplay reports financial download --bucket-id <id> --from 2026-01 --to 2026-06 --type sales

财务报告类型

类型	说明	文件名模式
earnings	收入和收益数据	earnings/earnings_YYYYMM_<id>.zip
sales	销售交易报告	sales/salesreport_YYYYMM.zip
payouts	付款发放报告	payouts/payout_YYYYMM.csv
play_balance	Play 余额报告（KRW）	play_balance_krw/...
wht_statements	预扣税报表	wht_statements/...

统计报告

列出可用的统计报告

# List all stats reports
gplay reports stats list --bucket-id <id>

# Filter by package name
gplay reports stats list --bucket-id <id> --package com.example.app

# Filter by type
gplay reports stats list --bucket-id <id> --type installs

# Filter by date range and package
gplay reports stats list --bucket-id <id> --package com.example.app --type installs --from 2026-01 --to 2026-06

下载统计报告

# Download installs report
gplay reports stats download --bucket-id <id> --package com.example.app --from 2026-01 --type installs

# Download to a specific directory
gplay reports stats download --bucket-id <id> --package com.example.app --from 2026-01 --type crashes --dir ./reports

# Download a range of months
gplay reports stats download --bucket-id <id> --package com.example.app --from 2026-01 --to 2026-06 --type ratings

统计报告类型

类型	说明	文件名模式
installs	安装/卸载数据	stats/installs/installs_<pkg>_YYYYMM_overview.csv
ratings	评分分布	stats/ratings/ratings_<pkg>_YYYYMM_overview.csv
crashes	崩溃发生数据	stats/crashes/crashes_<pkg>_YYYYMM_overview.csv
store_performance	商店商品详情页表现	stats/store_performance/...
subscriptions	订阅指标	financial-stats/subscriptions/...

标志参考

财务命令

标志	必填	描述
--bucket-id	是	GCS 存储桶 ID 或完整 URI
--type	否（列表：默认为 all）/ 是（下载）	报告类型：earnings、sales、payouts、play_balance、wht_statements、all
--from	否（列表）/ 是（下载）	起始月份 YYYY-MM
--to	否	结束月份 YYYY-MM（默认为 --from）
--dir	否	输出目录（默认为 .）
--output	否	输出格式：json、table、markdown
--pretty	否	美化 JSON 输出

统计命令

标志	必填	描述
--bucket-id	是	GCS 存储桶 ID 或完整 URI
--package	否（列表）/ 是（下载）	软件包名称筛选条件
--type	否（列表：默认为 all）/ 是（下载）	统计类型：installs、ratings、crashes、store_performance、subscriptions、all
--from	否（列表）/ 是（下载）	起始月份 YYYY-MM
--to	否	结束月份 YYYY-MM（默认为 --from）
--dir	否	输出目录（默认为 .）
--output	否	输出格式：json、table、markdown
--pretty	否	美化 JSON 输出

输出格式

列表输出

{
  "bucket": "pubsite_prod_rev_12345",
  "reports": [
    {"name": "earnings/earnings_202601_12345.zip", "size": 1234, "updated": "2026-02-01T00:00:00Z"}
  ]
}

下载输出

{
  "bucket": "pubsite_prod_rev_12345",
  "type": "earnings",
  "from": "2026-01",
  "to": "2026-01",
  "dir": "./reports",
  "files": [
    {"name": "earnings/earnings_202601_12345.zip", "path": "reports/earnings_202601_12345.zip", "size": 1234}
  ]
}

常见工作流

月度财务审查

# List last month's earnings
gplay reports financial list --bucket-id <id> --type earnings --from 2026-01 --output table

# Download all financial reports for Q1
gplay reports financial download --bucket-id <id> --from 2026-01 --to 2026-03 --type earnings --dir ./q1-reports

应用性能监控

# Check install trends
gplay reports stats list --bucket-id <id> --package com.example.app --type installs --from 2026-01

# Download crash data for analysis
gplay reports stats download --bucket-id <id> --package com.example.app --from 2026-01 --type crashes --dir ./crash-data

CI/CD 自动化报告收集

# Download all report types for archival
for type in earnings sales payouts; do
  gplay reports financial download --bucket-id $BUCKET_ID --from $(date -d "last month" +%Y-%m) --type $type --dir ./monthly-reports
done

故障排除

错误	原因	解决方法
authentication failed	未配置服务账号	运行 gplay auth login --service-account <path>
403 Forbidden	无权访问 GCS 存储桶	确保已在 Play Console 中邀请服务账号，并授予适当权限
404 Not Found	存储桶 ID 错误或没有报告	使用 Play Console > Download reports > Copy Cloud Storage URI 中的存储桶 ID（而非 URL 中的开发者 ID）
报告列表为空	指定日期范围内没有报告	检查 --from/--to 范围；并非每个月都有报告