版本控制

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

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

主要版本版本

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

Ad Manager API 的 Major 版本没有常规的发布频率 版本。只有在必要时才会发布新的主要版本。

就地发布

发布了向后兼容的更改，包括新功能和问题修复 当前 Major 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
  }
}

费用

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