兼容性和版本控制政策

此文档中，版本指的是 REST 资源的数据结构定义和功能的特定表现。兼容性指的是客户端能否针对特定版本的服务执行。向后兼容性指的是针对特定 API 主要版本编写的客户端无需修改即可继续正常运行于同一主要版本中的未来次要版本。

版本控制

亚马逊广告 API 中的 REST 资源使用 major.minor 格式进行独立版本控制。每个格式都是一个整数值，例如“3.0”。

目前，大多数资源只有一个版本。在为资源请求特定版本时，客户端使用 Accept 请求标头字段。如果服务支持指定的精确版本，则始终返回该资源的精确版本。

注意

在将来，未请求特定版本的客户端会收到最新版本。请求已弃用版本的客户端将获得最新兼容版本。请关注发布说明 以获取有关此行为实施的公告。

兼容性

亚马逊广告 API 服务中的资源保证在主版本中向后兼容。通过使用稳定的资源表现来保证向后兼容。

稳定的资源表现具有以下属性：

• 在资源表现中定义的属性在名称和值类型上保持不变。如果值类型是数组，则数组的可能值集合可以增加但不能减少。如果值类型是对象，则该对象也是稳定的表现。
• 属性的定义在主要版本内保持一致且不变。
• 可以在较新的次要版本中对资源表现定义新属性，但新属性不会改进或修改任何先前定义的属性的含义。
• 如果在值类型中定义了隐含的顺序，则该顺序及其含义在次要版本中将保持一致且不变。

在以下情况下，亚马逊广告 API 可能不会返回稳定的资源表现：

• 出现需要更改稳定资源表现形式的法律问题。
• 发现只能通过更改稳定资源表现来纠正的关键错误。
• 发现只能通过更改稳定资源表现来缓解的关键安全漏洞。

在不返回稳定资源表现的情况下，亚马逊广告 API 将告知更改并与客户通过合作来升级到新版本的稳定资源表现。

版本弃用

亚马逊广告 API 力求提前至少六个月通知客户关于主要版本的弃用。亚马逊广告 API 提供迁移指南来帮助客户迁移到最新版本。

在因法律问题、关键错误或关键安全漏洞而不再返回稳定资源表现的情况下，相关的稳定资源表现将尽快被弃用。