gpc-user-management

gpc-user-management

使用 GPC 管理开发者账号的用户、权限和测试人员。

使用场景

• 邀请用户加入 Google Play 开发者账号或将其移除
• 更新用户权限（开发者级别或按应用设置）
• 列出并审查哪些人有权访问开发者账号
• 在测试轨道（内部、Alpha、Beta）中添加或移除测试人员
• 从 CSV 文件批量导入测试人员
• 设置基于 Google Group 的测试人员访问权限

所需输入

• 已通过身份验证的 GPC — gpc auth status 必须显示有效凭据
• 开发者账号 ID — 用户命令必需（--developer-id 或 GPC_DEVELOPER_ID）
• 应用包名 — 测试人员命令和按应用授权必需（--app）
• 电子邮件地址 — 用于邀请用户或添加测试人员
• CSV 文件 — 用于批量导入测试人员（--file）

操作步骤

0. 验证设置

gpc auth status
gpc config get app

用户命令需要 --developer-id。设置一次即可：

export GPC_DEVELOPER_ID=1234567890

也可以在每条命令中传入：gpc users list --developer-id 1234567890。

1. 用户 — 列出并检查

# List all users in the developer account
gpc users list --developer-id 1234567890

# Get details for a specific user
gpc users get [email protected] --developer-id 1234567890

# JSON output for scripting
gpc users list --developer-id 1234567890 --json

**已在 v0.9.98 中修复：**在较旧版本中，users list 和 users get 会失败并提示“Pagination is not currently available”，因为 Google 现在要求使用不分页的请求。请升级到 v0.9.98 或更高版本。Google 会在单个响应中返回所有用户，因此 --limit 会在本地截取该响应，nextPageToken 始终为 null，且 --next-page 对用户列表没有影响。

2. 用户 — 邀请

邀请新用户并授予开发者级别权限，还可选择按应用授权：

# Invite with developer-level permissions
gpc users invite [email protected] \
  --role VIEW_APP_INFORMATION VIEW_FINANCIAL_DATA \
  --developer-id 1234567890

# Invite with per-app grants
gpc users invite [email protected] \
  --grant "com.example.app:VIEW_APP_INFORMATION,MANAGE_TESTING" \
  --developer-id 1234567890

# Combine developer-level and per-app permissions
gpc users invite [email protected] \
  --role VIEW_APP_INFORMATION \
  --grant "com.example.app:MANAGE_PRODUCTION_RELEASES" \
  --developer-id 1234567890

# Preview first
gpc users invite [email protected] \
  --role VIEW_APP_INFORMATION \
  --developer-id 1234567890 \
  --dry-run

Read: references/permissions.md，查看开发者级别和按应用设置的权限常量完整列表。

**注意：**权限变更可能需要最多 48 小时才能在 Google 的各个系统中生效。

3. 用户 — 更新权限

# Update developer-level permissions
gpc users update [email protected] \
  --role VIEW_APP_INFORMATION VIEW_FINANCIAL_DATA MANAGE_ORDERS \
  --developer-id 1234567890

# Update per-app grants
gpc users update [email protected] \
  --grant "com.example.app:MANAGE_PRODUCTION_RELEASES,MANAGE_TESTING" \
  --developer-id 1234567890

# Preview changes
gpc users update [email protected] \
  --role VIEW_APP_INFORMATION \
  --developer-id 1234567890 \
  --dry-run

4. 用户 — 移除

# Preview removal
gpc users remove [email protected] --developer-id 1234567890 --dry-run

# Remove
gpc users remove [email protected] --developer-id 1234567890

5. 测试人员 — 列出

# List testers for a track
gpc testers list --track internal
gpc testers list --track alpha
gpc testers list --track beta

# JSON output
gpc testers list --track beta --json

6. 测试人员 — 添加和移除

# Add individual testers (Google Group emails or individual emails)
gpc testers add [email protected] [email protected] --track internal

# Add a Google Group
gpc testers add [email protected] --track beta

# Add testers without auto-submitting changes for review
gpc testers add [email protected] --track beta --changes-not-sent-for-review

# Fail if the app is currently in review or rejected before modifying testers
gpc testers add [email protected] --track beta --error-if-in-review

# Remove testers
gpc testers remove [email protected] --track internal

# Remove testers without auto-submitting changes for review
gpc testers remove [email protected] --track internal --changes-not-sent-for-review

# Preview changes
gpc testers add [email protected] --track beta --dry-run

7. 授权 — 独立管理按应用设置的权限

gpc grants 可独立于用户邀请管理按应用设置的权限。当你需要精细控制各个用户在特定应用上可以执行的操作时，请使用此命令。

# List all grants for a user
gpc grants list [email protected] --developer-id 1234567890

# List grants for a specific app
gpc grants list [email protected] \
  --developer-id 1234567890 \
  --app com.example.app

# Create a new per-app grant
gpc grants create [email protected] \
  --app com.example.app \
  --permissions MANAGE_PRODUCTION_RELEASES VIEW_APP_INFORMATION \
  --developer-id 1234567890

# Update existing grant permissions
gpc grants patch [email protected] \
  --app com.example.app \
  --permissions VIEW_APP_INFORMATION \
  --developer-id 1234567890

# Remove a per-app grant (revokes app-specific access)
gpc grants delete [email protected] \
  --app com.example.app \
  --developer-id 1234567890

何时使用 gpc grants，何时使用 gpc users update --grant：

• 使用 gpc grants 管理现有用户的授权，而不修改其开发者级别角色
• 同时更改用户的账号级权限时，使用 gpc users invite --grant 或 gpc users update --grant

v0.9.87 新增：grants list 和 testers list 现在会返回统一的 --json 封装 { <key>, nextPageToken, meta.count, message? }，与其他列表命令保持一致。读取纯数组的脚本将无法继续运行——请更新脚本以解构对应的键字段。若测试轨道未配置 Google Groups，testers list 也会输出 googleGroups: []（始终包含 items 键）。从 GPC v0.9.83 起，users list 也使用相同的封装。

Read: references/permissions.md，查看按应用设置的权限常量完整列表。

8. 测试人员 — 从 CSV 批量导入

从包含电子邮件地址的 CSV 文件导入测试人员：

# Preview import
gpc testers import --track beta --file testers.csv --dry-run

# Import
gpc testers import --track beta --file testers.csv

CSV 格式 — 每行一个电子邮件地址：

email
[email protected]
[email protected]
[email protected]

Read: references/tester-workflows.md，了解常见的测试人员管理模式和 Google Group 最佳实践。

验证

• gpc users list --developer-id <id> 返回当前用户及其权限
• gpc users get <email> --developer-id <id> 显示用户当前的角色和授权
• gpc testers list --track <track> 返回指定测试轨道的测试人员
• 所有 --dry-run 命令都会显示将要进行的更改，而不会修改数据
• 所有命令均支持 JSON 输出（--json 标志）
• 权限变更可能需要最多 48 小时才能生效

故障模式 / 调试

症状	可能原因	解决方法
DEVELOPER_ID_REQUIRED	缺少 --developer-id 标志	设置 GPC_DEVELOPER_ID 环境变量，或传入 --developer-id
用户命令出现 PERMISSION_DENIED	服务账号缺少管理员权限	服务账号需要在 Play Console 中拥有“Admin”访问权限
USER_NOT_FOUND	该电子邮件不在开发者账号中	检查拼写；使用 gpc users list 进行验证
INVALID_GRANT 格式	--grant 语法错误	格式：com.example.app:PERM1,PERM2（应用与权限之间用冒号分隔，权限之间用逗号分隔）
INVALID_PERMISSION	未知的权限常量	查看 references/permissions.md 中的有效常量
权限未生效	传播延迟 48 小时	请等待；更改最终会生效——48 小时后进行验证
测试人员出现 TRACK_NOT_FOUND	跟踪版本不存在或名称错误	有效跟踪版本：internal、alpha、beta 或自定义跟踪版本名称
CSV 导入失败	CSV 格式或编码错误	确保使用 UTF-8 编码，每行一个电子邮件地址，并包含标题行 email
TESTER_LIMIT_EXCEEDED	跟踪版本已达到测试人员数量上限	Internal：100 人；Alpha/Beta：没有硬性上限，但建议规模扩大时使用 Google Groups

相关技能

• gpc-setup — 身份验证和开发者账号配置
• gpc-release-flow — 发布到测试人员可访问的测试跟踪版本
• gpc-ci-integration — 在 CI/CD 流水线中自动管理测试人员