版本控制

Ad Manager API 既有命名的主要版本发布，也有与当前主要版本向后兼容的就地发布。

服务、方法和字段可能会在主要版本（例如 v1）中的任何时间被标记为已弃用，但它们将一直受到支持，直到该主要版本停用为止。

主要版本发布

主要版本发布是指包含向后不兼容的 API 更改的版本。这些版本将命名，并具有不同的 API 端点。 之前的主要版本在迁移期间会受到支持。

Ad Manager API 没有针对主要版本的定期发布节奏。只有在必要时才会发布新的主要版本。

就地发布

向后兼容的更改（包括新功能和 bug 修复）会就地发布到当前的主要 API 版本。客户端必须处理 API 响应中的未知字段。

向后兼容性

对于主要版本内的更改，系统会保持向后兼容性。 兼容性定义如下：

  1. 源代码兼容性：针对先前版本编写的代码可以针对较新版本进行编译，并使用较新版本的客户端库成功运行。

  2. 线路兼容性：针对先前版本编写的代码可以与较新的服务器正确通信。也就是说，不仅输入和输出兼容，序列化和反序列化预期也会继续匹配。

  3. 语义兼容性：针对先前版本编写的代码会继续接收大多数合理开发者所期望的内容。

下表列出了 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
  }
}

cost 

// 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,
}