Ad Manager API 既有具名的主要版本，也有與目前主要版本回溯相容的就地發布版本。
服務、方法和欄位可能會在主要版本 (例如 v1) 內隨時標示為已淘汰，但會持續支援，直到該主要版本淘汰為止。
主要版本發布
主要版本是指 API 變更不相容於舊版的版本。這些版本會有不同的名稱和 API 端點。在遷移期間，系統會支援先前的主要版本。
Ad Manager API 主要版本沒有固定的發布頻率。只有在必要時，才會發布新的主要版本。
就地發布
回溯相容的變更 (包括新功能和錯誤修正) 會直接發布至目前的 Major API 版本。用戶端必須處理 API 回應中的不明欄位。
回溯相容性
主要版本內的變更會維持回溯相容性。相容性定義如下：
來源相容性：針對先前版本編寫的程式碼可針對較新版本編譯，並使用較新版本的用戶端程式庫順利執行。
傳輸相容性：針對先前版本編寫的程式碼可與較新的伺服器正確通訊。換句話說，不僅輸入和輸出內容相容，序列化和還原序列化預期也會繼續相符。
語意相容性：針對舊版編寫的程式碼會繼續收到大多數合理開發人員預期的內容。
下表列出 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,
}