開発者ポータル API バージョニング
この記事では、TealiumのAPIがどのようにバージョン管理されているか、何が破壊的変更を構成するか、およびバージョン間でどのように移行するかについて説明します。
仕組み
TealiumのAPIはカレンダーベースのバージョニング戦略を使用しています。破壊的変更が導入されたときのみ新しいバージョンがリリースされます。新しいエンドポイントやオプションのフィールドなどの非破壊的変更は、新しいバージョンをリリースせずに現在のバージョンに提供されます。このバージョニング戦略により、予測可能で安定した統合ターゲットと移行タイムラインが提供されます。
バージョニング形式
Tealiumは各バージョンを YYYY-MM 形式の日付で識別し、それに v を接頭辞として付け、URLパスに含めます：
https://api.tealiumapis.com/v{YYYY-MM}/{api-family}/{resource}
│ │ │ └─ リソースパス
│ │ └───────────── APIファミリー（cdp, iqなど）
│ └─────────────────────── カレンダーバージョン
└───────────────────────────────────────────────── グローバルホスト名
例えば：
https://api.tealiumapis.com/v2026-06/cdp/audiences
https://api.tealiumapis.com/v2026-06/cdp/labels
https://api.tealiumapis.com/v2026-10/cdp/audiences
地域ホスト名
管理する地域ホスト名はありません。Tealiumはトラフィックを最も近い地域にルーティングします。
破壊的および非破壊的変更
新しいバージョンは破壊的変更が導入されたときのみ作成されます。以下は破壊的変更と見なされます：
- レスポンス内の既存フィールドの削除または名前変更
- 既存フィールドのタイプ変更
- クエリパラメーターまたはパスパラメーターの名前変更または削除
- 既存エンドポイントのデフォルト動作の変更
- エンドポイントの完全な削除
- 必要なOAuth 2.0セキュリティスコープの変更
以下の変更は破壊的ではなく、現在のバージョンに提供されます：
- 新しいエンドポイントの追加
- リクエストまたはレスポンスに新しいオプションフィールドの追加
- 新しいオプションのクエリパラメーターの追加
- 新しい列挙値の追加（クライアントが未知の値を適切に処理することが期待される場合）
例えば：
2026年第1四半期リリース
├── 新しい /enrichment エンドポイント → 新バージョン不要
├── オプションのメタデータフィールド追加 → 新バージョン不要
└── 現バージョン維持: v2026-01
2026年第3四半期リリース
├── audiences フィルターパラメーター名変更 → 破壊的
├── 新しい /segments エンドポイント → 追加的（含まれる）
└── 新バージョン作成: v2026-06
URLが /v2026-01/cdp/... から /v2026-06/cdp/... に変更
サポートウィンドウ、非推奨シグナル、およびエンドオブライフタイムラインについての情報は、APIライフサイクルを参照してください。
段階的移行
サポートウィンドウ中に複数のバージョンが同時に実行されます。エンドポイントごとに移行を行い、各APIコールのURLパスでバージョンを独立して更新できます。すべてのエンドポイントを一度に移行する必要はありません。
開発者ポータルは、各バージョンのエンドポイントごとの変更ログを提供し、どのエンドポイントに破壊的変更があるか、具体的に何が変更されたかを正確に示します。エンドポイントに破壊的変更がない場合、既存のコードは古いバージョンと新しいバージョンのパスの両方で変更なしで動作します。
例えば、2026-01から2026-06へのアップグレード時：
/cdp/audiences : 2変更（フィルターパラメーター名変更、新しい必須フィールド）
/cdp/labels : 1変更（レスポンスページネーション形式）
/cdp/events : 変更なし
/cdp/connectors : 変更なし
この移行戦略により、/cdp/events と /cdp/connectors をすぐに新バージョンパスに切り替えることができ、コード変更は必要ありません。その後、/cdp/audiences と /cdp/labels の移行を別々に計画します。
# /audiences を新バージョンに移行（破壊的変更あり）
curl -X GET \
https://api.tealiumapis.com/v2026-06/cdp/audiences \
-H 'Authorization: Bearer {token}'
# /events を古いバージョンのままにする（バージョン間で変更なし）
curl -X GET \
https://api.tealiumapis.com/v2026-01/cdp/events \
-H 'Authorization: Bearer {token}'
ベストプラクティス
- バージョンを明示的に固定する：URLパスで常に特定のバージョンを使用します。本番環境ではリダイレクトや
latestエイリアスに依存しないでください。 - 非推奨ヘッダーを監視する：レスポンスが
Sunsetヘッダーを含むようになったときに警告する監視を構成します。 - 段階的に移行する：URLパスのバージョンをエンドポイントごとに更新します。古いバージョンと新しいバージョンのパスが同時にアクティブです。
- アップグレード前に変更ログを確認する：実際に破壊的変更があるエンドポイントのみに焦点を当てます。
- 準備ができたら中間バージョンをスキップする：すべてのバージョンを順番に進む必要はありません。現在のバージョンから最新バージョンに直接移行します。
最終更新日 :: 2026年September月23日