TiDB Cloud Starter 和 Essential 的项目 API 迁移指南

从 2026 年 4 月 15 日起，TiDB Cloud 为不同资源类型引入独立的项目类型。对于 TiDB Cloud Starter 和 Essential 实例，你现在既可以在 TiDB X 项目中管理它们，也可以在组织级别管理它们。更多信息，请参见TiDB X 实例的项目迁移常见问题。

本指南面向希望让大多数现有 v1beta 调用继续工作，并且仅对 TiDB Cloud Starter 和 Essential 实例的项目查找与集群创建进行最少改动的 API 调用方。

由于这些项目模型变更，请注意以下 API 变化：

• TiDB Cloud Starter 和 Essential 实例的 project_id 值可能会变化，因为这些实例可以在 TiDB Cloud 控制台中在项目之间移动。请勿将 project_id 值硬编码。
• 项目响应现在包含一个 type 字段。有关可能的取值，请参见项目类型取值。

项目 API 变更

GET /api/v1beta/projects

GET /api/v1beta/projects 现在会为每个项目返回一个 type 字段。

项目类型取值

如果你的应用程序只从项目响应中读取 id 和 name 字段，则无需进行任何更改。

如果你的应用程序需要区分项目类型（例如，筛选 dedicated 项目、TiDB X 项目或 TiDB X 虚拟项目），请开始读取 type 字段。

POST /api/v1beta/projects

如果你使用 POST /api/v1beta/projects 创建项目，请注意以下事项：

• 创建项目时，只有 dedicated 和 tidbx 是有效的 type 取值。
• 如果省略 type，API 默认会创建一个 dedicated 项目。

如何获取现有实例的项目 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

所需变更摘要