集群管理 API

本节介绍如何使用 Typesense Cloud 集群管理 API。

如需查看 Typesense Server API 文档，请访问此处。

工作流程

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

1. 创建新集群（这是一个异步过程，需要 4-5 分钟完成）
2. 轮询单个集群信息端点获取集群状态
3. 当集群状态变为 status: in_service 时，保存集群信息端点返回的 hostnames 字段
4. 为集群生成 Typesense API 密钥并将这些密钥存储在您的密钥管理系统中
5. 现在您可以使用步骤 3 中的主机名和步骤 4 中的 API 密钥，直接向新集群发起 Typesense API 调用
6. 使用完集群后，可以通过生命周期端点终止集群

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

创建新集群

此端点允许您在 Typesense Cloud 账户下配置新集群。

curl -X POST --location "https://cloud.typesense.org/api/v1/clusters" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY" \
    -d '{
          "memory": "0.5_gb",
          "vcpu": "2_vcpus_1_hr_burst_per_day",
          "regions": ["oregon"],
        }'

响应：

{
  "success": true,
  "cluster": {
    "id": "az9p28gwxfdsye40d",
    "name": null,
    "memory": "0.5_gb",
    "vcpu": "2_vcpus_1_hr_burst_per_day",
    "gpu": "no",
    "high_performance_disk": "no",
    "typesense_server_version": "0.23.1",
    "high_availability": "no",
    "search_delivery_network": "off",
    "load_balancing": "no",
    "regions": [
      "oregon"
    ],
    "auto_upgrade_capacity": null,
    "usage": {
      "runtime_hours": 0,
      "used_bandwidth_kb": {
        "last_7_days": {}
      }
    },
    "provisioned_by": {
      "user_name": "API Key: YOUR-API-KEY*****",
      "user_type": "API Key"
    },
    "provisioned_at": 1663382519,
    "status": "provisioning"
  }
}

参数

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

• memory 必填
• vcpu 必填
• regions 必填
• gpu
• high_availability
• search_delivery_network
• high_performance_disk
• typesense_server_version
• name
• auto_upgrade_capacity

memory

该集群应分配的内存大小。必填

可使用以下任意值：

memory
0.5_gb
1_gb
2_gb
4_gb
8_gb
16_gb
32_gb
64_gb
96_gb
128_gb
192_gb
256_gb
384_gb
512_gb
768_gb
1024_gb

vcpu

该集群应配置的 CPU 核心数量。必填

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

memory	vcpu
0.5_gb	2_vcpus_1_hr_burst_per_day
1_gb	2_vcpus_2_hr_burst_per_day
2_gb	2_vcpus_4_hr_burst_per_day
4_gb	2_vcpus_4_hr_burst_per_day 2_vcpus
8_gb	2_vcpus_7_hr_burst_per_day 2_vcpus 4_vcpus
16_gb	2_vcpus 4_vcpus_5_hr_burst_per_day 4_vcpus 8_vcpus
32_gb	4_vcpus 8_vcpus_4_hr_burst_per_day 8_vcpus 16_vcpus
64_gb	8_vcpus 16_vcpus 32_vcpus
96_gb	12_vcpus 24_vcpus 48_vcpus
128_gb	4_vcpus 16_vcpus 32_vcpus 64_vcpus
192_gb	24_vcpus 48_vcpus 96_vcpus
256_gb	8_vcpus 32_vcpus 64_vcpus 128_vcpus
384_gb	48_vcpus 96_vcpus 128_vcpus
512_gb	16_vcpus 64_vcpus 128_vcpus
768_gb	24_vcpus 96_vcpus 192_vcpus
1024_gb	32_vcpus 64_vcpus 128_vcpus

regions {#regions}

一个包含一个或多个地理区域的数组，用于指定节点应部署的位置。必填

• 对于非搜索分发网络(Search-Delivery-Network)集群，该数组应只包含一个区域
• 对于搜索分发网络(SDN)集群，该数组应包含3或5个区域，具体取决于SDN区域数量

下表列出了所有可用区域：

regions
n_california
oregon
n_virginia
ohio
canada
sao_paulo
ireland
london
paris
zurich
frankfurt
stockholm
milan
spain
cape_town
bahrain
uae
mumbai
hyderabad
singapore
jakarta
seoul
osaka
tokyo
melbourne
sydney

gpu {#gpu}

当设置为yes时，会在索引和搜索过程中使用GPU加速内置ML模型生成嵌入向量。

此选项仅适用于以下RAM/CPU配置：

ram	vcpu
8_gb	4_vcpus
16_gb	4_vcpus
16_gb	8_vcpus
32_gb	8_vcpus
32_gb	16_vcpus
64_gb	16_vcpus
64_gb	32_vcpus
128_gb	32_vcpus
128_gb	64_vcpus
192_gb	48_vcpus
256_gb	64_vcpus
384_gb	96_vcpus

默认值：no

high_availability {#high-availability}

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

默认值：no

search_delivery_network（搜索分发网络）

当不设置为 off 时，节点会被部署在不同区域，距离请求来源最近的节点将处理流量。

默认值: off

下表列出了所有可用选项：

search_delivery_network
off
3_regions
5_regions

重要提示： 启用搜索分发网络时，请确保将 high_availability 设置为 yes。

high_performance_disk（高性能磁盘）

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

默认值: no

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

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

typesense_server_version（Typesense 服务器版本）

用于该集群的 Typesense Server 版本。

默认值: 最新的正式发布版本。

name（名称）

用于在 Typesense Cloud 网页控制台中标识集群的字符串。

默认值: null

auto_upgrade_capacity（自动扩容）

设置为 true 时，当12小时滚动窗口内的RAM/CPU使用率超过最佳实践阈值时，集群将自动升级。

默认值: false

响应参数

大多数响应参数与上述请求参数类似。

以下是特定于响应的参数说明：

status（状态）

集群的运行状态。

可能的值包括：

status	描述
provisioning	集群节点正在部署中
initializing	Typesense 集群正在初始化
in_service	集群已就绪可供使用
deprovisioning	集群正在被解除部署
suspended	集群因计费问题被暂停
terminated	集群已被终止

生成 API 密钥

该端点可用于为您的集群生成 Typesense Server API 密钥。

只有当集群状态变为 in_service 后，您才能为其生成 API 密钥。新集群从 provisioning 状态到 in_service 状态至少需要 4 分钟。

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

响应：

{
  "success": true,
  "api_keys": {
    "admin_key": "cBKqFPEcGRAS7RIKi3h3FuJbj4Q9Rprk",
    "search_only_key": "y7CFw2zEgu09FFhoDgLzC99j0RwKi0kL"
  }
}

此 API 端点等同于在 Typesense Cloud 网页控制台的集群仪表板中点击"生成 API 密钥"按钮。

获取单个集群信息

该端点可用于获取单个集群的信息。

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

响应：

{
  "id": "nuj9s7k6vplrg15yp",
  "name": null,
  "memory": "0.5_gb",
  "vcpu": "2_vcpus_1_hr_burst_per_day",
  "gpu": "no",
  "high_performance_disk": "no",
  "typesense_server_version": "0.23.1",
  "high_availability": "yes",
  "search_delivery_network": "off",
  "load_balancing": "yes",
  "regions": [
    "mumbai",
    "mumbai",
    "mumbai"
  ],
  "auto_upgrade_capacity": null,
  "hostnames": {
    "load_balanced": "nuj9s7k6vplrg15yp.a1.typesense.net",
    "nodes": [
      "nuj9s7k6vplrg15yp-1.a1.typesense.net",
      "nuj9s7k6vplrg15yp-2.a1.typesense.net",
      "nuj9s7k6vplrg15yp-3.a1.typesense.net"
    ]
  },
  "usage": {
    "runtime_hours": 1,
    "used_bandwidth_kb": {
      "last_7_days": {}
    }
  },
  "provisioned_by": {
    "user_name": "API Key: sc4DyvAzf*****",
    "user_type": "API Key"
  },
  "provisioned_at": 1663616196,
  "status": "in_service"
}

列出所有集群

此端点可用于列出当前账户下的所有集群。

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

响应：

{
  "page": 1,
  "per_page": 1,
  "total": 2,
  "clusters": [
    {
      "id": "az9p28gwxfdsye40d",
      "name": null,
      "memory": "0.5_gb",
      "vcpu": "2_vcpus_1_hr_burst_per_day",
      "gpu": "no",
      "high_performance_disk": "no",
      "typesense_server_version": "0.23.1",
      "high_availability": "no",
      "search_delivery_network": "off",
      "load_balancing": "no",
      "regions": [
        "oregon"
      ],
      "auto_upgrade_capacity": false,
      "usage": {
        "runtime_hours": 5643,
        "used_bandwidth_kb": {
          "last_7_days": {}
        }
      },
      "provisioned_by": {
        "user_name": "John Doe",
        "user_type": "User"
      },
      "provisioned_at": 1663382520,
      "status": "initializing"
    }
  ]
}

参数

您可以在该端点使用以下查询参数：

per_page

每页返回的结果数量。

默认值：10

page

要获取的页码

默认值：1

更新集群属性

此端点可用于更新选定的集群属性：

• auto_upgrade_capacity（自动扩容）
• name（名称）

curl -X PATCH --location "https://cloud.typesense.org/api/v1/clusters/<ClusterID>" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY" \
    -d '{
          "auto_upgrade_capacity": true,
          "name": "New Name"
        }'

响应：

{
  "success": true,
  "cluster": {
    "id": "az9p28gwxfdsye40d",
    "name": "New Name",
    "memory": "0.5_gb",
    "vcpu": "2_vcpus_1_hr_burst_per_day",
    "gpu": "no",
    "high_performance_disk": "no",
    "typesense_server_version": "0.23.1",
    "high_availability": "no",
    "search_delivery_network": "off",
    "load_balancing": "no",
    "regions": ["oregon"],
    "auto_upgrade_capacity": true,
    "usage": {
      "runtime_hours": 5643,
      "used_bandwidth_kb": {
        "last_7_days": {}
      }
    },
    "provisioned_by": {
      "user_name": "John Doe",
      "user_type": "User"
    },
    "provisioned_at": 1663382520,
    "status": "in_service"
  }
}

终止集群

此端点用于终止运行中的集群。

此操作不可逆。出于安全和隐私考虑，集群一旦终止，其中的所有数据将被永久销毁。

curl -X POST --location "https://cloud.typesense.org/api/v1/clusters/<ClusterID>/lifecycle" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY" \
    -d '{
          "lifecycle_action": "terminate"
        }'

响应：

{
  "success": true,
  "message": "集群终止流程已启动"
}

参数

该端点接收一个参数 lifecycle_action，其值应设为 terminate