如何通过 Play Developer API 动态更新生产轨道的用户分发比例

本文详解如何使用 google play developer api 的 `edits.tracks.patch` 配合 `edits.commit` 正确更新生产轨道（production track）的用户分发比例（userfraction），避免因遗漏提交步骤导致控制台显示未同步的问题。

在自动化 android 应用灰度发布流程中，通过 Play Developer API 编程化调整 userFraction 是关键能力。但许多开发者（包括你）会遇到一个典型陷阱：调用 edits.tracks().patch() 后返回成功响应，Play console 界面却未更新用户分发比例——这并非缓存问题，而是 API 设计的「两阶段提交」机制未被完整执行。

google Play Publisher API 采用 Edit-based workflow：所有变更（如修改轨道、上传 APK/AAB、更新 release 配置）都需先在临时编辑会话（edit）中进行，最后必须显式调用 edits().commit() 才能将变更持久化并生效。patch() 仅修改本地 edit 对象，不触发实际部署。

✅ 正确流程如下（含关键修正）：

from googleapiclient import discovery from oauth2client.service_account import ServiceAccountCredentials import httplib2  # 初始化服务客户端（注意：v3 版本推荐使用 google-auth 替代 oauth2client，此处为兼容性示意） credentials = ServiceAccountCredentials.from_json_keyfile_name(     'key.json',      scopes=['https://www.googleapis.com/auth/androidpublisher'] ) http = credentials.authorize(httplib2.Http()) service = discovery.build('androidpublisher', 'v3', http=http)  # 1. 创建编辑会话 edit_request = service.edits().insert(body={}, packageName=package_name) edit_response = edit_request.execute() edit_id = edit_response['id'] print(f"Edit ID: {edit_id}")  # 2. 更新 production 轨道配置（注意：versionCodes 必须是已上传到该 edit 的有效版本号） track_update = service.edits().tracks().patch(     editId=edit_id,     packageName=package_name,     track='production',     body={         "releases": [             {                 "versionCodes": [str(target_code)],  # ⚠️ 必须为字符串数组（API 要求）                 "userFraction": float(user_fraction),  # 如 0.4 表示 40%                 "status": "inProgress"             }         ]     } ) track_response = track_update.execute() print("Track patch response:", track_response)  # 3. ✅ 关键步骤：提交编辑！否则所有变更仅存在于临时会话中 commit_response = service.edits().commit(     editId=edit_id,     packageName=package_name ).execute() print("Edit committed successfully:", commit_response)

? 重要注意事项：

• versionCodes 字段值必须是字符串类型数组（例如 [“12345”]），而非整数数组（[12345]），否则可能导致静默失败或版本不匹配；
• target_code 对应的版本必须已通过 edits.bundles.upload 或 edits.apks.upload 上传至当前 edit，否则 patch() 会报错 APK_VERSION_NOT_FOUND_IN_EDIT；
• userFraction 仅对 status: “inProgress” 的 release 生效，且最小粒度为 0.01（即 1%），取值范围 [0.01, 1.0]；
• 每次 commit() 后，该 edit 即失效，后续操作需新建 edit；
• 建议添加异常处理（如 HttpError）并校验 commit 返回状态，确保部署链路可靠。

完成上述三步后，Play Console 将在数秒内实时刷新「Production track」的用户分发比例，与 API 设置完全一致。这一机制保障了发布操作的原子性与可回滚性，是构建 CI/CD 自动化发布流水线的基石。