---
title: 開発者ポータル API バージョニング
description: この記事では、TealiumのAPIがどのようにバージョン管理されているか、何が破壊的変更を構成するか、およびバージョン間でどのように移行するかについて説明します。
url: https://docs.tealium.com/ja/administration/early-access/developer-portal/dev-portal-api-versioning/
---
## 仕組み

TealiumのAPIはカレンダーベースのバージョニング戦略を使用しています。破壊的変更が導入されたときのみ新しいバージョンがリリースされます。新しいエンドポイントやオプションのフィールドなどの非破壊的変更は、新しいバージョンをリリースせずに現在のバージョンに提供されます。このバージョニング戦略により、予測可能で安定した統合ターゲットと移行タイムラインが提供されます。

### バージョニング形式

Tealiumは各バージョンを `YYYY-MM` 形式の日付で識別し、それに `v` を接頭辞として付け、URLパスに含めます：

```none
https://api.tealiumapis.com/v{YYYY-MM}/{api-family}/{resource}
│                         │         │            └─ リソースパス
│                         │         └───────────── APIファミリー（cdp, iqなど）
│                         └─────────────────────── カレンダーバージョン
└───────────────────────────────────────────────── グローバルホスト名
```

例えば：

```none
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セキュリティスコープの変更

以下の変更は破壊的ではなく、現在のバージョンに提供されます：

* 新しいエンドポイントの追加
* リクエストまたはレスポンスに新しいオプションフィールドの追加
* 新しいオプションのクエリパラメーターの追加
* 新しい列挙値の追加（クライアントが未知の値を適切に処理することが期待される場合）

例えば：

```none
2026年第1四半期リリース
├── 新しい /enrichment エンドポイント        → 新バージョン不要
├── オプションのメタデータフィールド追加   → 新バージョン不要
└── 現バージョン維持: v2026-01

2026年第3四半期リリース
├── audiences フィルターパラメーター名変更  → 破壊的
├── 新しい /segments エンドポイント          → 追加的（含まれる）
└── 新バージョン作成: v2026-06
    URLが /v2026-01/cdp/... から /v2026-06/cdp/... に変更
```

サポートウィンドウ、非推奨シグナル、およびエンドオブライフタイムラインについての情報は、[APIライフサイクル](https://docs.tealium.com/dev-portal-api-lifecycle/)を参照してください。

## 段階的移行

サポートウィンドウ中に複数のバージョンが同時に実行されます。エンドポイントごとに移行を行い、各APIコールのURLパスでバージョンを独立して更新できます。すべてのエンドポイントを一度に移行する必要はありません。

開発者ポータルは、各バージョンのエンドポイントごとの変更ログを提供し、どのエンドポイントに破壊的変更があるか、具体的に何が変更されたかを正確に示します。エンドポイントに破壊的変更がない場合、既存のコードは古いバージョンと新しいバージョンのパスの両方で変更なしで動作します。

例えば、2026-01から2026-06へのアップグレード時：

```none
/cdp/audiences    : 2変更（フィルターパラメーター名変更、新しい必須フィールド）
/cdp/labels       : 1変更（レスポンスページネーション形式）
/cdp/events       : 変更なし
/cdp/connectors   : 変更なし
```

この移行戦略により、`/cdp/events` と `/cdp/connectors` をすぐに新バージョンパスに切り替えることができ、コード変更は必要ありません。その後、`/cdp/audiences` と `/cdp/labels` の移行を別々に計画します。

```bash
# /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}'
```

## ベストプラクティス

1. **バージョンを明示的に固定する**：URLパスで常に特定のバージョンを使用します。本番環境ではリダイレクトや `latest` エイリアスに依存しないでください。
1. **非推奨ヘッダーを監視する**：レスポンスが `Sunset` ヘッダーを含むようになったときに警告する監視を構成します。
1. **段階的に移行する**：URLパスのバージョンをエンドポイントごとに更新します。古いバージョンと新しいバージョンのパスが同時にアクティブです。
1. **アップグレード前に変更ログを確認する**：実際に破壊的変更があるエンドポイントのみに焦点を当てます。
1. **準備ができたら中間バージョンをスキップする**：すべてのバージョンを順番に進む必要はありません。現在のバージョンから最新バージョンに直接移行します。