集群配置变更 API

当您通过 Typesense Cloud 网页控制台或使用集群管理 API 创建集群后，您可以使用以下 API 来更改其配置。

工作流程

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

1. 安排新的配置变更（这是一个异步过程）
2. 轮询单个配置变更信息端点以获取配置变更状态
3. 如果需要取消待处理的配置变更，使用更新配置变更端点

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

安排配置变更

此端点允许您更改运行中集群的内存、CPU、高可用性以及 Typesense Server 版本。

您可以在下面的负载中跳过不需要更改的字段。

curl -X POST --location "https://cloud.typesense.org/api/v1/clusters/<ClusterId>/configuration-changes" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY" \
    -d '{
          "new_memory": "1_gb",
          "new_vcpu": "2_vcpus_2_hr_burst_per_day",
          "new_typesense_server_version: "0.24.1",
          "new_high_availability: "yes",
          "perform_change_at": 1787923647,
          "notification_email_addresses": ["email@example.com"]
        }'

响应：

{
  "success": true,
  "configuration_change": {
    "id": "ecf1d570-7f49-47ef-b648-41ccf7eaf5d2",
    "status": "pending",
    "created_at": 1687996347,
    "updated_at": 1687996347,
    "perform_change_at": 1787923647,
    "completed_at": null,
    "old_memory": "0.5_gb",
    "old_vcpu": "2_vcpus_1_hr_burst_per_day",
    "old_gpu": null,
    "old_high_performance_disk": null,
    "old_typesense_server_version": "0.23.1",
    "old_high_availability": "no",
    "old_load_balancing": "no",
    "new_memory": "1_gb",
    "new_vcpu": "2_vcpus_2_hr_burst_per_day",
    "new_gpu": null,
    "new_high_performance_disk": null,
    "new_typesense_server_version": "0.24.1",
    "new_high_availability": "yes",
    "new_load_balancing": "yes",
    "notification_email_addresses": [
      "email@example.com"
    ]
  }
}

注意

同一时间只能有一个配置变更处于活动/待处理状态。

参数

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

• perform_change_at 必填
• new_memory
• new_vcpu
• new_gpu
• new_high_availability
• new_high_performance_disk
• new_typesense_server_version

perform_change_at

配置变更应执行的 Unix 时间戳。

必须是一个未来的时间戳。

new_memory

集群应分配的 内存 大小。

可使用 此处 列出的任意值。

new_vcpu

集群应分配的 CPU 核心数。

特定 CPU 配置仅适用于特定的内存配置。此处 的表格列出了所有可用配置。

new_gpu

当设置为 yes 时，启用 GPU 加速功能，在使用内置 ML 模型进行索引和搜索时加速嵌入向量的生成。

GPU 加速仅适用于特定的 RAM/CPU 配置。可用配置详见此表。

new_high_availability

当设置为 yes 时，系统会在 3 个不同的数据中心至少部署 3 个节点，形成一个高可用性(HA)集群，您的数据会自动在所有节点之间复制。

注意

高可用性一旦启用就无法关闭。

如需关闭 HA，您需要新建一个非 HA 集群，重新索引数据，然后终止原 HA 集群。

new_high_performance_disk

当设置为 yes 时，配置的硬盘将与运行节点的物理服务器共置。

重要提示： 此选项仅在以下情况下可用：

• 集群已启用高可用性
• 集群未使用突发型 CPU

new_typesense_server_version

指定要将集群切换到的 Typesense Server 版本。

获取单个配置变更

此端点可用于获取单个配置变更的详细信息。

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

响应：

{
  "id": "ecf1d570-7f49-47ef-b648-41ccf7eaf5d2",
  "status": "pending",
  "created_at": 1687996347,
  "updated_at": 1687996347,
  "perform_change_at": 1787923647,
  "completed_at": null,
  "old_memory": "0.5_gb",
  "old_vcpu": "2_vcpus_1_hr_burst_per_day",
  "old_gpu": null,
  "old_high_performance_disk": null,
  "old_typesense_server_version": "0.23.1",
  "old_high_availability": "no",
  "old_load_balancing": "no",
  "new_memory": "1_gb",
  "new_vcpu": "2_vcpus_2_hr_burst_per_day",
  "new_gpu": null,
  "new_high_performance_disk": null,
  "new_typesense_server_version": "0.24.1",
  "new_high_availability": "yes",
  "new_load_balancing": "yes",
  "notification_email_addresses": [
    "email@example.com"
  ]
}

status {#status}

status 字段可能包含以下值之一：

status	描述
pending	配置变更处于待执行状态，将在指定的 perform_change_at 时间戳执行。
in_progress	配置变更正在进行中，无法再取消。
canceled	配置变更已被取消。
succeeded	配置变更已成功完成。completed_at 字段会显示该配置变更完成的时间。
failed	配置变更因内部错误而失败。

列出所有配置变更

此端点可用于列出集群的所有配置变更。

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

响应:

{
  "page": 1,
  "per_page": 1,
  "total": 10,
  "configuration_changes": [
    "id": "ecf1d570-7f49-47ef-b648-41ccf7eaf5d2",
    "status": "pending",
    "created_at": 1687996347,
    "updated_at": 1687996347,
    "perform_change_at": 1787923647,
    "completed_at": null,
    "old_memory": "0.5_gb",
    "old_vcpu": "2_vcpus_1_hr_burst_per_day",
    "old_gpu": null,
    "old_high_performance_disk": null,
    "old_typesense_server_version": "0.23.1",
    "old_high_availability": "no",
    "old_load_balancing": "no",
    "new_memory": "1_gb",
    "new_vcpu": "2_vcpus_2_hr_burst_per_day",
    "new_gpu": null,
    "new_high_performance_disk": null,
    "new_typesense_server_version": "0.24.1",
    "new_high_availability": "yes",
    "new_load_balancing": "yes",
    "notification_email_addresses": [
      "email@example.com"
    ]
  ]
}

参数

此端点可使用以下查询参数：

per_page

每页返回的结果数量。

默认值: 10

page

要获取的页码

默认值: 1

取消待处理的配置变更

您可以使用此端点取消待处理的配置变更。

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

响应：

{
  "success": true,
  "configuration_change": {
    "id": "ecf1d570-7f49-47ef-b648-41ccf7eaf5d2",
    "status": "canceled",
    "created_at": 1687996347,
    "updated_at": 1687996347,
    "perform_change_at": 1787923647,
    "completed_at": null,
    "old_memory": "0.5_gb",
    "old_vcpu": "2_vcpus_1_hr_burst_per_day",
    "old_high_performance_disk": null,
    "old_typesense_server_version": "0.23.1",
    "old_high_availability": "no",
    "old_load_balancing": "no",
    "new_memory": "1_gb",
    "new_vcpu": "2_vcpus_2_hr_burst_per_day",
    "new_high_performance_disk": null,
    "new_typesense_server_version": "0.24.1",
    "new_high_availability": "yes",
    "new_load_balancing": "yes",
    "notification_email_addresses": [
      "email@example.com"
    ]
  }
}