版本管理

Ad Manager API 既有具名的主要版本，也有與目前主要版本回溯相容的就地發布版本。

服務、方法和欄位可能會在主要版本 (例如 v1) 內隨時標示為已淘汰，但會持續支援，直到該主要版本淘汰為止。

主要版本發布

主要版本是指 API 變更不相容於舊版的版本。這些版本會有不同的名稱和 API 端點。在遷移期間，系統會支援先前的主要版本。

Ad Manager API 主要版本沒有固定的發布頻率。只有在必要時，才會發布新的主要版本。

就地發布

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