版本管理

Ad Manager API 同時包含命名的主要版本和 可回溯相容的內部版本至目前的主要版本。

服務、方法和欄位可在主要版本 (例如 v1) 中隨時標示為已淘汰，但在主要版本停用前，這些項目仍會持續受到支援。

主要版本發布

主要版本發布內容定義為含有回溯不相容 API 變更的版本。系統會將這些版本命名，並採用不同的 API 端點。 在遷移期間支援先前的主要版本。

Ad Manager API 並未針對主要版本提供定期發布時程。新的主要版本只會在必要時發布。

就地發布

回溯相容的變更 (包括新功能和錯誤修正) 會直接發布至目前的主要 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
  }
}

費用

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