App-Store-Connect-CLI 实战：App Tag territories 在 API 4.5 中的弃用迁移指南

【免费下载链接】App-Store-Connect-CLIFast, scriptable CLI for the App Store Connect API. Automate TestFlight, builds, submissions, signing, analytics, screenshots, subscriptions, and more项目地址https://gitcode.com/gh_mirrors/ap/App-Store-Connect-CLI点击查看免费下载Apple 在 App Store Connect API 4.5 中正式弃用了 app-tag 的territories关系、独立的 territory 端点及相关列表参数。App-Store-Connect-CLI 在不删除任何稳定命令的前提下通过继续转发请求 单次 stderr 警告的兼容策略平滑过渡本文基于 release-notes-app-tag-territories.md 与仓库源码完整梳理弃用范围、警告触发逻辑、新旧脚本写法对比帮助你快速完成迁移并避免在 CI 流水线中被警告噪音干扰。弃用背景API 4.5 对 app-tag territories 做了什么Apple 的 API 4.5 release notes 明确弃用了 app-tag 的territories关系以及两个 territory 相关的端点full-resource territory 端点返回 tag 关联的完整 territory 资源ID-only territory 端点仅返回 territory 关系 ID。同时territory 相关的列表参数也被一并废弃不过 Apple 发布的 OpenAPI 快照本仓库维护于 docs/openapi/latest.json中仍然暴露这些操作与参数因此基于该快照的代码生成与校验在短期内不会直接报错——这正是弃用期常见的文档已标记、契约仍存在状态。在 App-Store-Connect-CLI 中每个 app tag 资源目前暴露三个字段其中territories正是被弃用的那一个见 internal/asc/app_tags.go 中AppTagAttributes的定义以及 commands/app-tags.mdx 的字段说明name—— App Store Connect 返回的标签名称visibleInAppStore—— 该标签当前是否在商店前台可见territories—— 旧版商店前台关系API 4.5 起弃用。CLI 的兼容策略保留全部命令与行为只加警告与直接移除功能不同CLI 采取了保守的兼容路线详见 docs/release-notes-app-tag-territories.md保留既有 flag、HTTP 请求与分页行为弃用期间请求仍会被原样转发给 App Store Connect API没有移除任何稳定命令也没有宣布具体的移除日期JSON stdout 与 API 错误行为完全不变脚本对标准输出的解析不会受到影响。这意味着你现有的脚本在弃用期内依然可用但需要尽快从告警信息中识别出哪些调用命中了弃用面并主动迁移。警告触发点一次调用只告警一次CLI 在以下场景会每次调用向 stderr 输出一条警告不会污染 stdout 的 JSON 输出app-tags list/app-tags view中携带 territory 选择如--fields中包含territories或--include territories单独执行territories与territories-links命令续页 URL--next指向的links.next中带有 territory 参数例如fields[territories]、limit[territories]、includeterritories或路径以/territories结尾。警告文案固定为Warning: App-tag territories are deprecated in API 4.5; remove territory selections and lookups. Requests are still forwarded for compatibility.这段逻辑的实现位于 internal/cli/apps/app_tags_deprecation.go核心函数appTagTerritoriesRequested(fields, includes, nextURL)会依次检查--fields/--include中是否包含territories解析nextURL判断路径是否以/territories结尾检查续页 URL 的查询参数中是否存在fields[territories]、limit[territories]遍历fields[appTags]与include参数逐个值拆分后比对是否为territories。任一条件命中即调用warnAppTagTerritoryDeprecation()输出告警见 internal/cli/apps/app_tags_deprecation.go。list与view的 Exec 中均在发起请求前完成该检测见 internal/cli/apps/app_tags.go 与 internal/cli/apps/app_tags.go而territories/territories-links命令则无条件告警见 internal/cli/apps/app_tags.go 与 internal/cli/apps/app_tags.go。测试用例 internal/cli/cmdtest/app_tags_deprecation_test.go 覆盖了全部告警分支view --include territories、view --fields name,territories、list --fields territories、list --next含includeterritories、fields[appTags]territories、fields[territories]currencylimit[territories]2三种续页形态同时验证了不带 territory 选择的plain view与plain list不产生告警。新写法核心标签读取请彻底去掉 territory 选择对于核心的标签读取需求文档给出的推荐写法是asc app-tags list --app APP_ID --fields name,visibleInAppStore asc app-tags view --app APP_ID --id TAG_ID迁移时请对照检查并移除以下参数参数状态说明--fields中的territories值移除只保留name、visibleInAppStore--include territories移除不再内联 territory 资源--territory-fields移除仅支持currency依赖--include territories才生效--territory-limit移除取值范围 1–50依赖--include territories才生效关于这些参数的校验细节可以看 internal/cli/apps/app_tags.go 中维护的合法值列表--fields只接受name、visibleInAppStore、territories--include只接受territories--territory-fields只接受currency。此外代码强制了参数间的依赖关系不带--include territories时使用--territory-fields或--territory-limit会直接报错见 internal/cli/apps/app_tags.go提示--territory-fieldsrequires--include territories。这一设计意味着即便你想继续用旧参数也不能只写一半。注意Apple 在 4.5 release notes 中没有为 territory 查询提供等效替代方案。如果你依赖 territory 数据进行跨商店前台覆盖分析需要自行评估替代数据源例如其他资源的 territory 关系CLI 本身不会自动改写这些请求。旧写法保留遗留 territory 查询仍可用带警告如果你在过渡期内仍需使用遗留查询CLI 依旧支持只是每次调用都会收到一条 stderr 警告见 commands/app-tags.mdx# 在 list/view 中内联 territory警告 asc app-tags list --app APP_ID --include territories --territory-fields currency asc app-tags view --app APP_ID --id TAG_ID --include territories --territory-fields currency # 独立的遗留 territory 命令警告 asc app-tags territories --id TAG_ID asc app-tags territories --id TAG_ID --fields currency asc app-tags territories --id TAG_ID --paginate asc app-tags territories-links --id TAG_ID两条遗留命令的差异territories返回完整 territory 资源对应底层GetAppTagTerritories请求/v1/appTags/{id}/territories见 internal/asc/app_tags.goterritories-links只返回 territory 关系 ID对应底层GetAppTagTerritoriesRelationships请求/v1/appTags/{id}/relationships/territories见 internal/asc/app_tags.go。两条命令都支持--limit1–200、--next与--paginate分页行为与其他列表命令一致--next传入的 URL 会经过ValidateNextURL校验仅接受 App Store Connect 域名下的合法续页 URL见 internal/cli/cmdtest/app_tags_next_validation_test.go 中的非法 URL 用例与ExitUsage退出码断言。不受影响的部分links 与可见性更新保持无警告有两类操作不在弃用范围内可以放心继续使用而不会收到任何告警app-tags links --app APP_ID—— 返回 app 与 tag 之间的关系 ID底层GetAppTagsRelationshipsForApp请求/v1/apps/{id}/relationships/appTags不涉及 territory保持无警告见 internal/asc/app_tags.go。app-tags update—— 更新 tag 的visibleInAppStore可见性。该命令只有visibleInAppStore一个可变字段且强制要求--visible-in-app-store与--confirm同时出现见 internal/cli/apps/app_tags.go 的必填校验。典型可见性切换写法# 让标签在商店前台显示 asc app-tags update --id TAG_ID --visible-in-app-store --confirm # 将标签从可见集合中移除不删除底层 tag 资源 asc app-tags update --id TAG_ID --visible-in-app-storefalse --confirm此外所有命令的JSON stdout 输出格式、分页契约与 API 错误语义均保持不变这也是本次兼容策略对脚本最友好的部分只要不读取 stderr弃用期内脚本行为与之前完全一致。迁移检查清单结合文档与源码建议按以下顺序完成迁移审计调用面搜索脚本与 CI 配置中所有asc app-tags调用标记包含territories、--include territories、--territory-fields、--territory-limit或--next带 territory 参数的行。替换核心读取将list/view改为只带name、visibleInAppStore字段的写法见上文新写法这是唯一官方推荐的迁移路径。评估遗留依赖对确实需要 territory 数据的自动化任务确认是否有替代数据源Apple 未提供等价替代需自行决策。处理告警噪音若暂时无法移除遗留调用可在 CI 日志中过滤该条固定警告文案但不要将其静默后长期忽视——文档明确没有宣布移除日期意味着 API 侧随时可能真正下线这些能力。回归验证app-tags links与app-tags update应保持零告警territories/territories-links每次调用恰好一条警告可用仓库中的测试用例 internal/cli/cmdtest/app_tags_deprecation_test.go 作为行为基准。总结API 4.5 对 app-tag territory 的弃用是典型的渐进式弃用CLI 通过保留全部命令、请求与分页行为仅增加每次调用一条 stderr 警告的轻量手段让开发者有充分时间迁移。核心动作只有一件事——让所有常规标签读取脱离 territory 选择同时保留links与update作为无警告的稳定操作。按照本文的检查清单逐项核对即可在弃用期内安全完成过渡并为 API 侧最终下线做好准备。赞分享【免费下载链接】App-Store-Connect-CLIFast, scriptable CLI for the App Store Connect API. Automate TestFlight, builds, submissions, signing, analytics, screenshots, subscriptions, and more项目地址https://gitcode.com/gh_mirrors/ap/App-Store-Connect-CLI点击查看免费下载相关推荐App Store Connect API 4.4.1 遗留资源弃用App-Store-Connect-CLI 的 29 个命令叶子迁移指南App Store Connect API 4.4.1 遗留资源弃用App Store Connect CLI 的 29 个命令叶子迁移指南 本文基于仓库文档App Store Connect CLI 的 AppInfo.kidsAgeBand 弃用迁移指南API 4.5 移除后的替代用法与警告行为解析App Store Connect CLI 的 AppInfo.kidsAgeBand 弃用迁移指南API 4.5 移除后的替代用法与警告行为解析 App SApp-Store-Connect-CLI 4.4.0 Apple Ads 迁移指南Platform API v1 直连与 Campaign Management API v5 弃用App Store Connect CLI 4.4.0 Apple Ads 迁移指南Platform API v1 直连与 Campaign Manageme上一篇UFO 推测式多动作执行Speculative Multi-Action Execution实战指南一次 LLM 调用批量预测与验证多个 UI 动作下一篇Linux-NetSpeed内核管理详解如何安全安装和卸载加速模块创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考