バージョニング

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

cost 

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