バージョニング

Ad Manager API には、名前付きのメジャー バージョン リリースと、現在のメジャー バージョンとの下位互換性のあるインプレース リリースの両方があります。

サービス、メソッド、フィールドは、同じ期間内でいつでも非推奨としてマークされる可能性があります。 ただし、メジャー バージョン（v1 など）は、そのメジャー バージョンまで引き続きサポートされます。 廃止されました。

メジャー バージョン リリース

メジャー バージョン リリースは、下位互換性のない API 変更を含むリリースとして定義されます。これらのリリースには名前が付けられ、異なる API エンドポイントが使用されます。以前のメジャー バージョンは、移行期間中はサポートされます。

アド マネージャー API では、メジャー バージョンのリリース頻度は決まっていません。新しいメジャー バージョンは、必要な場合にのみリリースされます。

インプレース リリース

新機能やバグ修正などの下位互換性のある変更は、現在のメジャー API バージョンにそのままリリースされます。クライアントが不明なフィールドを処理する必要がある API レスポンスで使用できます。

下位互換性

下位互換性は、メジャー バージョン内の変更に対して維持されます。 互換性は次のように定義されます。

  1. ソースの互換性: 以前のリリースに対して記述されたコードはコンパイル可能 実行され、新しいバージョンの Deployment の クライアント ライブラリを使用します。

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