第一章：Google Play Console 账号与环境准备
接入 Google Play API 的第一步是完成开发者账号注册、应用创建以及 API 服务的启用与授权配置。本章围绕账号与环境的完整初始化流程，覆盖原理、操作步骤、关键配置与常见错误。
目标：掌握从零开始创建 Google Play 开发者账号、注册应用、启用 Google Play Android Developer API、配置 OAuth 2.0 凭证，并验证 API 可访问性的完整方法。
1.1 核心原理
Google Play API 基于 REST 架构，通过 OAuth 2.0 协议进行身份认证。所有 API 调用需要满足以下条件：
- 一个已注册并缴费的 Google Play 开发者账号
- 一个在 Play Console 中创建的应用（package name）
- 一个已启用 Google Play Android Developer API 的 Google Cloud 项目
- 一个具有适当权限的 OAuth 2.0 服务账号或 Web 客户端
API 调用链路：客户端应用 → OAuth 令牌 → Google Play API 端点 → 返回数据。
1.2 实现流程
| 步骤 | 操作 | 平台 | 耗时 |
|---|---|---|---|
| 1 | 注册 Google Play 开发者账号 | Google Play Console | ~15 分钟 |
| 2 | 创建应用并获取 Package Name | Google Play Console | ~5 分钟 |
| 3 | 启用 Google Play Android Developer API | Google Cloud Console | ~2 分钟 |
| 4 | 创建 OAuth 2.0 服务账号并授权 | Google Cloud Console | ~10 分钟 |
| 5 | 测试 API 连通性 | 本地终端 / 脚本 | ~5 分钟 |
1.3 详细操作与配置
1.3.1 注册开发者账号
访问 Google Play Console，使用 Google 账号登录。支付一次性的 $25 注册费（仅支持信用卡/借记卡）。注册完成后即可进入控制台。
建议：使用专用的“开发者”Google 账号，不要混用个人账号，便于权限隔离。
1.3.2 创建应用
在 Play Console 首页点击“创建应用”，填写以下信息：
- 应用名称：最终面向用户的名称
- 默认语言：通常选择 English (United States) 或中文
- 应用或游戏：根据产品类型选择
- 免费或付费：免费应用或付费应用
创建后，记录下应用的 Package Name（如 com.example.myapp），后续 API 调用需要用到。
1.3.3 启用 Google Play Android Developer API
打开 Google Cloud Console，确保已关联到 Play Console 相同的 Google 账号。
- 创建新项目（或选择已有项目）
- 进入“API 和服务” → “库”
- 搜索 Google Play Android Developer API
- 点击“启用”
启用后，项目将会获得访问 Play API 的能力。可通过以下命令验证服务状态：
# 使用 gcloud 命令行工具查看已启用服务（需先安装 gcloud）
gcloud services list --enabled --project=YOUR_PROJECT_ID1.3.4 配置 OAuth 2.0 访问权限
Google Play API 使用 OAuth 2.0 进行认证，推荐使用服务账号方式（适合后端脚本）。
- 在 Google Cloud Console 进入“IAM 和管理” → “服务账号”
- 创建服务账号，命名如
play-api-service - 生成并下载 JSON 密钥文件（保存到安全位置）
- 回到 Google Play Console，进入“用户和权限”
- 添加新的用户，输入服务账号的邮箱地址（如
play-api-service@PROJECT.iam.gserviceaccount.com） - 赋予权限：至少勾选“查看应用信息”、“管理订单和订阅”等 API 所需权限
权限最小化原则：只赋予 API 调用必需的最小权限，例如仅检查订阅状态时，不需要“发布应用”权限。
1.4 调试与测试
使用 curl 或 google-api-python-client 测试 API 连通性。以下是用 curl 获取 OAuth 令牌并调用 products 接口的示例：
# 1. 使用服务账号 JSON 密钥生成 JWT（需工具或脚本）
# 2. 交换 access_
# 3. 调用 API
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access- --impersonate-service-account=play-api-service@PROJECT.iam.gserviceaccount.com)" \
"https://androidpublisher.googleapis.com/androidpublisher/v3/applications/com.example.myapp/purchases/subscriptions//tokens/<>" 如果返回 HTTP 200 且包含 JSON 数据，则环境配置成功；若返回 401/403，检查服务账号权限或 OAuth 范围。
1.5 常见错误与解决方法
| 错误 | 原因 | 修复 |
|---|---|---|
HTTP 401 Unauthorized |
OAuth 令牌无效或过期 | 重新生成 access_；确认服务账号邮箱正确 |
HTTP 403 Forbidden |
服务账号未被授予 Play Console 权限 | 在 Play Console “用户和权限”中添加服务账号并勾选相应权限 |
API not enabled |
Google Play Android Developer API 未在项目中启用 | 检查 Cloud Console 中 API 状态并启用 |
Project not linked |
Cloud 项目未关联到 Play Console | 在 Play Console 中设置开发账号 → API 访问 → 关联 Cloud 项目 |
1.6 性能与稳定性建议
- 令牌缓存：OAuth 访问令牌有效期通常为 1 小时，建议缓存并在过期前刷新，避免频繁请求。
- 错误重试：对 5xx 错误实施指数退避重试策略。
- 使用专用项目：不要将多个应用的 API 凭证混在同一个 Cloud 项目内，避免权限污染。
- 日志记录：记录所有 API 请求的 trace ID，便于问题排查。