版本管理

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

服務、方法和欄位隨時都可以在不過，主要版本 (例如第 1 版) 會持續受到支援，直到該主要版本為止已淘汰

主要版本

主要版本定義為不具回溯相容性的版本 API 變更。系統會將這些版本命名，並採用不同的 API 端點。系統支援先前的主要版本，

Ad Manager REST API 沒有定期使用主要版本版本。新的主要版本只會在必要時發布。

就地發布

發布回溯相容的變更 (包括新功能和錯誤修正) 固定在目前的主要 API 版本上用戶端必須處理不明欄位。

回溯相容性

針對主要版本中的變更，系統會維持回溯相容性。相容性的定義如下：

原始碼相容性：針對先前版本編譯內容編寫的程式碼搭配較新的版本運作，且能使用較新的用戶端程式庫
傳輸相容性：針對先前版本編寫的程式碼與較新的伺服器正常通訊換句話說，不單只是輸入但 Cloud Storage 是支援序列化與去序列化的會繼續比對。
語意相容性：針對先前版本編寫的程式碼繼續進行享有最合理的開發人員期望

下表列舉 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,
}