版本控制

本指南介绍了 Merchant API 如何处理版本控制、发布及其不同版本的生命周期。

版本控制方案

Merchant API 在子 API 级别采用版本控制策略。这意味着，每个 API（例如 Merchant API 中的 Products）都将有自己的版本生命周期。

版本控制格式和演示

  • 稳定的子 API 版本：如果子 API 处于稳定版本，则其所有方法都处于稳定版本。稳定的子 API 版本表示为 vX（例如 v1、v2）。这些是可用于生产环境的主要版本。

  • Alpha 子 API 版本：如果某个子 API 处于 Alpha 阶段，则其所有方法都处于 Alpha 阶段。Alpha 子 API 版本表示为 vXalpha（例如 v1alpha、v2alpha）。它们包含实验性抢先体验功能，旨在用于测试和快速迭代。Alpha 版不保证稳定性，没有明确的生命周期，并且可能会在提前 30 天通知的情况下进行更改或停用。

版本更改

  • 主要版本递增（例如，从 v1 到 v2）：表示存在向后不兼容的破坏性更改，需要开发者采取行动。只有稳定子 API 的重大更改才会导致版本号发生变化。例如，从 v1 到 v2。

  • 次要更改：向后兼容的添加或修复以对现有主要版本的更改形式呈现。此类变更将在相应主要版本的版本说明中详细说明。对子 API 的非破坏性添加将发布到最新稳定版本的 Alpha 渠道，或直接发布到最新稳定版本。

停用政策

我们会定期弃用旧版 Merchant 子 API。我们承诺，对于稳定的主要版本 (vX)，自正式宣布弃用之日起，将提供 12 个月的弃用期限。

例如，如果我们于 2026 年 1 月 15 日弃用 Products 子 API 的 v1，则该 API 最早将于 2027 年 1 月 15 日停用。在此日期之后，将无法再使用该子 API 的早期版本。

子 API 版本和生命周期状态

下表列出了 Merchant API 各个子 API 的最新版本：

子 API 版本 状态
账号 v1
v1beta 		有效
将于 2026 年 2 月 28 日停用
转化次数 v1
v1beta 		有效
将于 2026 年 2 月 28 日停用
数据源 v1
v1beta 		有效
将于 2026 年 2 月 28 日停用
商品目录 v1
v1beta 		有效
将于 2026 年 2 月 28 日停用
问题解决情况 v1
v1beta 		有效
将于 2026 年 2 月 28 日停用
本地 Feed 合作伙伴关系 v1
v1beta 		有效
将于 2026 年 2 月 28 日停用
通知 v1
v1beta 		有效
将于 2026 年 2 月 28 日停用
订单跟踪 v1
v1beta 		有效
将于 2026 年 2 月 28 日停用
产品 v1
v1beta 		有效
将于 2026 年 2 月 28 日停用
Product Studio v1alpha 有效
促销活动 v1
v1beta 		有效
将于 2026 年 2 月 28 日停用
配额 v1
v1beta 		有效
将于 2026 年 2 月 28 日停用
报告 v1
v1beta 		有效
将于 2026 年 2 月 28 日停用
评价 v1alpha
v1 beta 		有效
将于 2026 年 2 月 28 日停用

最佳做法

  • 请定期查看版本说明和最新更新，了解新版本、重大更新、改进以及有关子 API 启动和弃用的公告。
  • 如果某个子 API 有两个或更多稳定版本，我们建议您始终使用最新版本。
  • 设计应用时，应使其能够妥善处理各种子 API 错误，包括网络问题、速率限制以及可能随较新的子 API 版本引入的新错误代码或消息。
  • 不要等到子 API 版本即将停用时才开始规划升级。在新版本发布后立即开始评估和测试。
  • 如果您有功能请求或对子 API 路线图有疑虑，请与我们联系，提出问题或提供反馈。如需了解如何联系 Merchant API 团队以获取技术支持，请参阅获取 Merchant API 方面的帮助。