Typesense 中文文档

# 集群克隆 API

当您通过 Typesense Cloud 网页控制台或使用集群管理 API 创建集群后，您可以使用以下 API 创建该集群的克隆副本。

# 工作流程

使用此 API 时的典型调用序列如下：

  1. 启动新的克隆操作（这是一个异步过程）
  2. 轮询克隆操作信息端点获取克隆操作状态
  3. 如果需要取消待处理的克隆操作，使用更新克隆操作端点

本文档其余部分将详细介绍各个端点。

# 启动克隆操作

此端点允许您克隆一个正在运行的现有集群。

curl -X POST --location "https://cloud.typesense.org/api/v1/clusters/<ClusterId>/cloning-operations" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY" \
    -d '{
          "typesense_server_version": "28.0",
          "target_region": "oregon",
          "notification_email_addresses": ["email@example.com"]
        }'

响应：

{
  "success": true,
  "cloning_operation": {
    "id": "fbff4b22-23d3-46e8-a599-144b622f4dd4",
    "status": "pending",
    "created_at": 1743046821,
    "updated_at": 1743046821,
    "completed_at": null,
    "source_region": "oregon",
    "target_region": "oregon",
    "typesense_server_version": "28.0",
    "target_cluster_reference_id": null,
    "notification_email_addresses": [
      "email@example.com"
    ]
  }
}

注意

同一时间只能有一个克隆操作处于活动/待处理状态。

# 参数

您可以在上述 API 调用的负载中使用以下任意参数：

# typesense_server_version

克隆集群的 Typesense Server 版本。如果未指定，将使用源集群的版本。

# target_region

克隆集群应部署的区域。必须是此处列出的有效区域之一。

# notification_email_addresses

当克隆操作完成或失败时将收到通知的电子邮件地址数组。

# 获取单个克隆操作

此端点可用于获取有关单个克隆操作的信息。

curl -X GET --location "https://cloud.typesense.org/api/v1/clusters/<ClusterID>/cloning-operations/<OperationId>" \
      -H "Accept: application/json" \
      -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY"

响应：

{
  "id": "fbff4b22-23d3-46e8-a599-144b622f4dd4",
  "status": "succeeded",
  "created_at": 1742607328,
  "updated_at": 1742608267,
  "completed_at": 1742608267,
  "source_region": "oregon",
  "target_region": "oregon",
  "typesense_server_version": "28.0.rc29",
  "target_cluster_reference_id": "815p962i73hnjcdud",
  "notification_email_addresses": [
    "email@example.com",
    "email@example.net"
  ]
}

# status

status 字段可以取以下任一值：

status 描述
pending 克隆操作等待执行中
in_progress 克隆操作正在进行中，此时无法再取消
canceled 克隆操作已被取消
succeeded 克隆操作成功完成。completed_at 字段会显示该克隆操作完成的时间，target_cluster_reference_id 将包含新创建集群的 ID。
failed 克隆操作因内部错误而失败

# 列出所有克隆操作

此端点可用于列出集群的所有克隆操作。

curl -X GET --location "https://cloud.typesense.org/api/v1/clusters/<ClusterID>/cloning-operations?per_page=1" \
      -H "Accept: application/json" \
      -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY"

响应:

{
  "page": 1,
  "per_page": 1,
  "total": 3,
  "cloning_operations": [
    {
      "id": "fbff4b22-23d3-46e8-a599-144b622f4dd4",
      "status": "succeeded",
      "created_at": 1742607328,
      "updated_at": 1742608267,
      "completed_at": 1742608267,
      "source_region": "oregon",
      "target_region": "oregon",
      "typesense_server_version": "28.0.rc29",
      "target_cluster_reference_id": "815p962i73hnjcdud",
      "notification_email_addresses": [
        "email@example.com",
        "email@example.net"
      ]
    }
  ]
}

# 参数

此端点支持以下查询参数:

# per_page

每页返回的结果数量。

默认值: 10

# page

要获取的页码

默认值: 1

# 取消待处理的克隆操作

此端点可用于取消待处理的克隆操作。

curl -X PATCH --location "https://cloud.typesense.org/api/v1/clusters/<ClusterID>/cloning-operations/<OperationID>" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json" \
      -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY" \
      -d '{
        "status": "canceled"
      }'

响应：

{
  "success": true,
  "cloning_operation": {
    "id": "fbff4b22-23d3-46e8-a599-144b622f4dd4",
    "status": "canceled",
    "created_at": 1742607328,
    "updated_at": 1742607328,
    "completed_at": null,
    "source_region": "oregon",
    "target_region": "oregon",
    "typesense_server_version": "28.0.rc29",
    "target_cluster_reference_id": null,
    "notification_email_addresses": [
      "email@example.com",
      "email@example.net"
    ]
  }
}

:::提示 注意 只有处于 pending 状态的克隆操作才能被取消。

这个状态只是临时存在的，因为克隆操作正在等待被异步工作进程拾取。 :::

← 响应码 →