TiDB Cloud Starter と Essential のための Project API 移行ガイド

2026 年 4 月 15 日より、TiDB Cloud はリソースタイプごとに個別のプロジェクトタイプを導入します。TiDB Cloud Starter と Essential インスタンスについては、TiDB X プロジェクト内、または組織レベルで管理できるようになります。詳細は、TiDB X Instances の Project Migration FAQ を参照してください。

このガイドは、既存の v1beta 呼び出しの大部分を引き続き動作させつつ、TiDB Cloud Starter と Essential インスタンスに対するプロジェクト検索およびクラスタ作成にのみ最小限の変更を加えたい API 呼び出し元を対象としています。

これらのプロジェクトモデルの変更により、以下の API 変更に注意してください。

• TiDB Cloud Starter と Essential インスタンスの project_id 値は、TiDB Cloud コンソールでこれらのインスタンスをプロジェクト間で移動できるため、変更される可能性があります。project_id の値をハードコードしないでください。
• プロジェクトのレスポンスには type フィールドが含まれるようになりました。指定可能な値については、Project type values を参照してください。

Project API の変更

GET /api/v1beta/projects

GET /api/v1beta/projects は、各プロジェクトに対して type フィールドを返すようになりました。

Project type values

アプリケーションがプロジェクトレスポンスから id と name フィールドのみを読み取る場合、変更は不要です。

アプリケーションでプロジェクトタイプを区別する必要がある場合（たとえば、dedicated プロジェクト、TiDB X プロジェクト、または TiDB X 仮想プロジェクトをフィルタリングする場合）は、type フィールドの読み取りを開始してください。

POST /api/v1beta/projects

POST /api/v1beta/projects を使用してプロジェクトを作成する場合は、以下に注意してください。

• プロジェクト作成時に有効な type 値は dedicated と tidbx のみです。
• type を省略すると、API はデフォルトで dedicated プロジェクトを作成します。

既存インスタンスの project ID を取得する方法

すでに TiDB Cloud Starter または Essential インスタンスを所有しており、現在の project_id のみが必要な場合は、その値をハードコードする代わりに、以下の方法を使用してください。

1. クラスタ詳細エンドポイントを呼び出します。

   GET https://serverless.tidbapi.com/v1beta1/clusters/{clusterId}
   

2. レスポンスから labels["tidb.cloud/project"] を読み取ります。

   {
     "clusterId": "1048576",
     "labels": {
       "tidb.cloud/project": "2293484"
     }
   }
   

3. 取得した project_id を既存の v1beta エンドポイントで使用します。例:

   • GET /api/v1beta/projects/{project_id}/clusters/{cluster_id}
   • DELETE /api/v1beta/projects/{project_id}/clusters/{cluster_id}
   • GET /api/v1beta/projects/{project_id}/clusters/{cluster_id}/imports
   • POST /api/v1beta/projects/{project_id}/clusters/{cluster_id}/imports

必要な変更の概要