版本控制

Ad Manager REST API 包含已命名的主要版本发布版本和向后兼容的就地版本。

服务、方法和字段可能会随时标记为“已弃用” 主要版本（如 v1），但直到该主要版本才开始支持这些版本版本已停用。

主要版本版本

主要版本是指具有向后不兼容状态的版本 API 更改。这些版本将被命名并具有不同的 API 端点。迁移期间支持之前的主要版本。

Ad Manager REST API 的 Major 版本没有常规发布频率版本。新的主要版本将仅在必要时发布。

就地发布

发布了向后兼容的更改，包括新功能和问题修复当前 Major API 版本。客户端必须处理未知字段。

向后兼容性

主要版本中的更改会保持向后兼容性。兼容性的定义如下：

源代码兼容性：针对之前的版本编译的代码与较新版本的应用一起成功运行客户端库。
线路兼容性：针对先前版本编写的代码与较新的服务器正常通信。换句话说，和输出兼容，但序列化和反序列化预期满足继续匹配。
语义兼容性：针对先前版本编写的代码继续获得最合理的开发者所期望的东西

下表列举了 API 变更的类型，以及变更是否适用向后兼容性

服务

更改类型	向后兼容
添加新服务	是
移除服务	否

方法

更改类型	向后兼容
添加新方法	是
移除方法	否
更改方法的请求或响应类型	否

对象

更改类型	向后兼容
添加必填字段	否
添加可选字段	是
将字段移入或移出子消息	否
将字段从必填字段更改为选填字段	是
将字段从选填字段改为必填字段	否
移除不可变的限制	是
添加不可变限制	否

枚举

更改类型	向后兼容
添加枚举值	是
移除枚举值	否

已弃用的字段行为

替换字段

对于具有替换项的字段，如果可行，这两个字段都将填充。更新时，可以设置任一字段。更新中同时包含这两个字段请求会导致 INVALID_ARGUMENT 错误。

请参考以下架构：

{
  // The cost of this Foo in micros.
  // Deprecated: Use `cost` instead.
  "costMicros": number,

  // The cost of this Foo.
  "cost": {
    object (Money)
  }
}

读取响应会使用等效值填充这两个字段：

{
  "costMicros": 1250000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 250000000
  }
}

更新请求可以设置任一值。如果同时包含这两个字段，系统会生成 INVALID_ARGUMENT 个错误：

costMicros

// Update payload
{
  "costMicros": 1500000
}

// Response payload
{
  "costMicros": 1500000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

费用

// Update payload
{
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

// Response payload
{
  "costMicros": 1500000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

两者都有

// Update payload
{
  "costMicros": 1250000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

// Response payload
{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "costMicros",
            "description": "Cannot update both costMicros and cost."
          }
        ]
      }
    ]
  }
}

已停用的功能

如果某项产品功能不再提供，相应字段将被标记为且可能返回语义上适当的默认值。最新动态可以忽略。

{
  // The salesperson split amount in micros.
  // Deprecated: The Sales Management feature has been deprecated. This field
  // will always be `0`.
  "salespersonSplitMicros": number,
}