API 文档由 Redocly 提供

ClickHouse Cloud 的 OpenAPI 规范 (1.0)

下载 OpenAPI 规范:下载

ClickHouse 支持：[email protected] URL: https://clickhouse.ac.cn/docs/en/cloud/manage/openapi?referrer=openapi-130664

获取可用组织列表

返回与请求中的 API 密钥关联的单个组织的列表。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": [
    ]
}

获取组织详细信息

返回单个组织的详细信息。为了获取详细信息，身份验证密钥必须属于该组织。

路径参数
organizationId
必需
string <uuid>

请求的组织 ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

更新组织详细信息

更新组织字段。需要 ADMIN 身份验证密钥角色。

路径参数
organizationId
必需
string <uuid>

要更新的组织 ID。

请求体模式：application/json
name
string

组织名称。

object (OrganizationPrivateEndpointsPatch)

响应

请求示例

内容类型
application/json
{
  • "name": "string",
  • "privateEndpoints": {
    }
}

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

获取组织详细信息

返回单个组织的详细信息。为了获取详细信息，身份验证密钥必须属于该组织。

路径参数
organizationId
必需
string <uuid>

请求的组织 ID。

响应

响应示例

内容类型
application/json
{
  • "status": 400,
  • "error": "string"
}

组织服务列表

返回组织中的所有服务列表。

路径参数
organizationId
必需
string <uuid>

请求的组织 ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": [
    ]
}

创建新服务

在组织中创建一个新服务，并返回当前服务状态和访问服务的密码。服务异步启动。

路径参数
organizationId
必需
string <uuid>

将拥有服务的组织的 ID。

请求体模式：application/json
name
string

服务的名称。最多 50 个字符的字母数字字符串，包含空格。

提供商
string
枚举： "aws" "gcp" "azure"

云提供商

区域
string
枚举： "ap-south-1" "ap-southeast-1" "eu-central-1" "eu-west-1" "eu-west-2" "us-east-1" "us-east-2" "us-west-2" "ap-southeast-2" "ap-northeast-1" "us-east1" "us-central1" "europe-west4" "asia-southeast1" "eastus" "eastus2" "westus3" "germanywestcentral"

服务区域。

层级
string
枚举： "development" "production" "dedicated_high_mem" "dedicated_high_cpu" "dedicated_standard" "dedicated_standard_n2d_standard_4" "dedicated_standard_n2d_standard_8" "dedicated_standard_n2d_standard_32" "dedicated_standard_n2d_standard_128"

服务的层级：'development'、'production'、'dedicated_high_mem'、'dedicated_high_cpu'、'dedicated_standard'、'dedicated_standard_n2d_standard_4'、'dedicated_standard_n2d_standard_8'、'dedicated_standard_n2d_standard_32'、'dedicated_standard_n2d_standard_128'。生产服务会进行扩展，开发服务则是固定大小。Azure 服务不支持开发层级

数组类型为 对象 (IpAccessListEntry)

允许访问服务的 IP 地址列表

minTotalMemoryGb
数字 12 的倍数 [ 24 .. 720 ]
已弃用

已弃用 - 对副本数量不为默认值的 services 不准确。自动扩展期间三个 worker 的最小内存（以 GB 为单位）。仅适用于 'production' 服务。必须是 12 的倍数，且大于或等于 24。

maxTotalMemoryGb
数字 12 的倍数 [ 24 .. 720 ]
已弃用

已弃用 - 对副本数量不为默认值的 services 不准确。自动扩展期间三个 worker 的最大内存（以 GB 为单位）。仅适用于 'production' 服务。必须是 12 的倍数，对于非付费服务，小于或等于 360，对于付费服务，小于或等于 720。

minReplicaMemoryGb
数字 4 的倍数 [ 8 .. 240 ]

自动扩展期间每个副本的最小总内存（以 GB 为单位）。仅适用于 'production' 服务。必须是 4 的倍数，且大于或等于 8。

maxReplicaMemoryGb
数字 4 的倍数 [ 8 .. 240 ]

自动扩展期间每个副本的最大总内存（以 GB 为单位）。仅适用于 'production' 服务。必须是 4 的倍数，对于非付费服务，小于或等于 120，对于付费服务，小于或等于 240。

numReplicas
数字 [ 3 .. 20 ]

服务的副本数量。必须介于 3 到 20 之间。请联系支持启用此功能。

空闲扩展
布尔值

设置为 true 时，允许服务在空闲时缩放到零。默认情况下为 true。

idleTimeoutMinutes
数字

设置最小空闲超时时间（以分钟为单位）。必须 >= 5 分钟。

备份 ID
string <uuid>

可选的备份 ID，用作新服务的初始状态。使用此 ID 时，新实例的区域和层级必须与原始实例的值相同。

加密密钥
string

可选的客户提供的磁盘加密密钥

加密假设的角色标识符
string

可选的角色，用于磁盘加密

私有端点 ID
数组类型为 字符串

私有端点列表

私有预览条款已勾选
布尔值

接受私有预览条款和条件。在私有预览的情况下，仅在组织中创建第一个服务时需要此参数。

响应

请求示例

内容类型
application/json
{
  • "name": "string",
  • "provider": "aws",
  • "region": "ap-south-1",
  • "tier": "development",
  • "ipAccessList": [
    ],
  • "minTotalMemoryGb": 48,
  • "maxTotalMemoryGb": 360,
  • "minReplicaMemoryGb": 16,
  • "maxReplicaMemoryGb": 120,
  • "numReplicas": 3,
  • "idleScaling": true,
  • "idleTimeoutMinutes": 0,
  • "backupId": "eb7cea43-10b2-42dd-8819-ab9aed37565f",
  • "encryptionKey": "string",
  • "encryptionAssumedRoleIdentifier": "string",
  • "privateEndpointIds": [
    ],
  • "privatePreviewTermsChecked": true
}

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

获取服务详细信息

返回属于该组织的服务

路径参数
organizationId
必需
string <uuid>

拥有服务的组织的 ID。

服务 ID
必需
string <uuid>

请求服务的 ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

更新服务基本信息

更新服务的基本信息，例如服务名称或 IP 访问列表。

路径参数
organizationId
必需
string <uuid>

拥有服务的组织的 ID。

服务 ID
必需
string <uuid>

要更新的服务的 ID。

请求体模式：application/json
name
string

服务的名称。最多 50 个字符的字母数字字符串，包含空格。

对象 (IpAccessListPatch)
对象 (InstancePrivateEndpointsPatch)

响应

请求示例

内容类型
application/json
{
  • "name": "string",
  • "ipAccessList": {
    },
  • "privateEndpointIds": {
    }
}

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

删除服务

删除服务。服务必须处于停止状态，并且在执行此方法调用后异步删除。

路径参数
organizationId
必需
string <uuid>

拥有服务的组织的 ID。

服务 ID
必需
string <uuid>

要删除的服务的 ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}

获取私有端点配置

设置私有端点所需的信息

路径参数
organizationId
必需
string <uuid>

请求的组织 ID。

服务 ID
必需
string <uuid>

请求服务的 ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

更新服务状态

启动或停止服务

路径参数
organizationId
必需
string <uuid>

拥有服务的组织的 ID。

服务 ID
必需
string <uuid>

要更新状态的服务的 ID。

请求体模式：application/json
命令
string
枚举： "start" "stop"

更改状态的命令：'start'、'stop'。

响应

请求示例

内容类型
application/json
{
  • "command": "start"
}

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

更新服务自动扩展设置 已弃用

更新服务的最小和最大总内存限制以及空闲模式扩展行为。内存设置仅适用于 "production" 服务，必须是 12 的倍数，从 24 GB 开始。请联系支持以启用 numReplicas 的调整。

路径参数
organizationId
必需
string <uuid>

拥有服务的组织的 ID。

服务 ID
必需
string <uuid>

要更新扩展参数的服务的 ID。

请求体模式：application/json
minTotalMemoryGb
数字 12 的倍数 [ 24 .. 720 ]
已弃用

已弃用 - 对副本数量不为默认值的 services 不准确。自动扩展期间三个 worker 的最小内存（以 GB 为单位）。仅适用于 'production' 服务。必须是 12 的倍数，且大于或等于 24。

maxTotalMemoryGb
数字 12 的倍数 [ 24 .. 720 ]
已弃用

已弃用 - 对副本数量不为默认值的 services 不准确。自动扩展期间三个 worker 的最大内存（以 GB 为单位）。仅适用于 'production' 服务。必须是 12 的倍数，对于非付费服务，小于或等于 360，对于付费服务，小于或等于 720。

numReplicas
数字 [ 3 .. 20 ]

服务的副本数量。必须介于 3 到 20 之间。请联系支持启用此功能。

空闲扩展
布尔值

设置为 true 时，允许服务在空闲时缩放到零。默认情况下为 true。

idleTimeoutMinutes
数字

设置最小空闲超时时间（以分钟为单位）。必须 >= 5 分钟。

响应

请求示例

内容类型
application/json
{
  • "minTotalMemoryGb": 48,
  • "maxTotalMemoryGb": 360,
  • "numReplicas": 3,
  • "idleScaling": true,
  • "idleTimeoutMinutes": 0
}

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

更新服务自动扩展设置

更新服务的每个副本的最小和最大内存限制以及空闲模式扩展行为。内存设置仅适用于 "production" 服务，必须是 4 的倍数，从 8 GB 开始。请联系支持以启用 numReplicas 的调整。

路径参数
organizationId
必需
string <uuid>

拥有服务的组织的 ID。

服务 ID
必需
string <uuid>

要更新扩展参数的服务的 ID。

请求体模式：application/json
minReplicaMemoryGb
数字 4 的倍数 [ 8 .. 240 ]

单个副本的最小自动扩展内存（以 GB 为单位）。仅适用于 'production' 服务。必须是 4 的倍数，且大于或等于 8。

maxReplicaMemoryGb
数字 4 的倍数 [ 8 .. 240 ]

单个副本的最大自动扩展内存（以 GB 为单位）。仅适用于 'production' 服务。必须是 4 的倍数，对于非付费服务，小于或等于 120，对于付费服务，小于或等于 240。

numReplicas
数字 [ 3 .. 20 ]

服务的副本数量。必须介于 3 到 20 之间。请联系支持启用此功能。

空闲扩展
布尔值

设置为 true 时，允许服务在空闲时缩放到零。默认情况下为 true。

idleTimeoutMinutes
数字

设置最小空闲超时时间（以分钟为单位）。必须 >= 5 分钟。

响应

请求示例

内容类型
application/json
{
  • "minReplicaMemoryGb": 16,
  • "maxReplicaMemoryGb": 120,
  • "numReplicas": 3,
  • "idleScaling": true,
  • "idleTimeoutMinutes": 0
}

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

更新服务密码

设置服务的新的密码

路径参数
organizationId
必需
string <uuid>

拥有服务的组织的 ID。

服务 ID
必需
string <uuid>

要更新密码的服务的 ID。

请求体模式：application/json
newPasswordHash
string

可选的密码哈希。用于避免通过网络传输密码。如果未提供，则会生成一个新的密码，并在响应中提供。否则，将使用此哈希。算法：echo -n "yourpassword" | sha256sum | tr -d '-' | xxd -r -p | base64

newDoubleSha1Hash
string

用于 MySQL 协议的可选双 SHA1 密码哈希。如果未提供 newPasswordHash，则会忽略此密钥，并使用生成的密码。算法：echo -n "yourpassword" | sha1sum | tr -d '-' | xxd -r -p | sha1sum | tr -d '-'

响应

请求示例

内容类型
application/json
{
  • "newPasswordHash": "字符串",
  • "newDoubleSha1Hash": "字符串"
}

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

获取Prometheus指标

返回服务的Prometheus指标。

路径参数
organizationId
必需
string <uuid>

拥有服务的组织的 ID。

服务 ID
必需
string <uuid>

请求服务的 ID。

响应

响应示例

内容类型
application/json
{
  • "status": 400,
  • "error": "string"
}

服务备份列表

返回服务的所有备份列表。 最新的备份在列表中排在最前面。

路径参数
organizationId
必需
string <uuid>

拥有备份的组织的ID。

服务 ID
必需
string <uuid>

创建备份的服务的ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": [
    ]
}

获取备份详细信息

返回单个备份信息。

路径参数
organizationId
必需
string <uuid>

拥有备份的组织的ID。

服务 ID
必需
string <uuid>

创建备份的服务的ID。

备份 ID
必需
string <uuid>

请求备份的ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

获取服务备份配置

返回服务备份配置。

路径参数
organizationId
必需
string <uuid>

拥有服务的组织的 ID。

服务 ID
必需
string <uuid>

服务的ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

更新服务备份配置

更新服务备份配置。 需要 ADMIN 身份验证密钥角色。 使用空值设置属性将重置属性为其默认值。

路径参数
organizationId
必需
string <uuid>

拥有服务的组织的 ID。

服务 ID
必需
string <uuid>

服务的ID。

请求体模式：application/json
backupPeriodInHours
数字

每次备份之间的时间间隔（以小时为单位）。

backupRetentionPeriodInHours
数字

备份可用的最短时间（以小时为单位）。

backupStartTime
string

执行备份的时间（以 HH:MM 格式表示，在 UTC 时区中评估）。 如果已定义，备份周期将重置为每 24 小时。

响应

请求示例

内容类型
application/json
{
  • "backupPeriodInHours": 0,
  • "backupRetentionPeriodInHours": 0,
  • "backupStartTime": "字符串"
}

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

获取所有密钥列表

返回组织中的所有密钥列表。

路径参数
organizationId
必需
string <uuid>

请求的组织 ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": [
    ]
}

创建密钥

创建新的 API 密钥。

路径参数
organizationId
必需
string <uuid>

拥有密钥的组织的ID。

请求体模式：application/json
name
string

密钥的名称。

expireAt
字符串 <日期时间>

密钥过期的时间戳。 如果不存在或为空，则密钥永不过期。 ISO-8601。

state
string
枚举： "已启用" "已禁用"

密钥的初始状态：'已启用'、'已禁用'。 如果未提供，新密钥将为 '已启用'。

对象 (ApiKeyHashData)
roles
数组类型为 字符串
项目枚举： "admin" "developer"

分配给密钥的角色列表。 包含至少 1 个元素。

响应

请求示例

内容类型
application/json
{
  • "name": "string",
  • "expireAt": "2019-08-24T14:15:22Z",
  • "state": "已启用",
  • "hashData": {
    },
  • "roles": [
    ]
}

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

获取密钥详细信息

返回单个密钥详细信息。

路径参数
organizationId
必需
string <uuid>

请求的组织 ID。

keyId
必需
string <uuid>

请求密钥的ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

更新密钥

更新 API 密钥属性。

路径参数
organizationId
必需
string <uuid>

拥有密钥的组织的ID。

keyId
必需
string <uuid>

要更新的密钥的ID。

请求体模式：application/json
name
string

密钥的名称

roles
数组类型为 字符串
项目枚举： "admin" "developer"

分配给密钥的角色列表。 包含至少 1 个元素。

expireAt
字符串 <日期时间>

密钥过期的时间戳。 如果不存在或为空，则密钥永不过期。 ISO-8601。

state
string
枚举： "已启用" "已禁用"

密钥的状态：'已启用'、'已禁用'。

响应

请求示例

内容类型
application/json
{
  • "name": "string",
  • "roles": [
    ],
  • "expireAt": "2019-08-24T14:15:22Z",
  • "state": "已启用"
}

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

删除密钥

删除 API 密钥。 只能删除未用于对活动请求进行身份验证的密钥。

路径参数
organizationId
必需
string <uuid>

拥有密钥的组织的ID。

keyId
必需
string <uuid>

要删除的密钥的ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}

列出组织成员

返回组织中的所有成员列表。

路径参数
organizationId
必需
string <uuid>

请求的组织 ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": [
    ]
}

获取成员详细信息

返回单个组织成员详细信息。

路径参数
organizationId
必需
string <uuid>

成员所属组织的ID。

userId
必需
string <uuid>

请求用户的ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

更新组织成员。

更新组织成员角色。

路径参数
organizationId
必需
string <uuid>

成员所属组织的ID。

userId
必需
string <uuid>

要修补的用户的ID

请求体模式：application/json
role
string
枚举： "admin" "developer"

成员在组织中的角色。

响应

请求示例

内容类型
application/json
{
  • "role": "admin"
}

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

删除组织成员

从组织中删除用户

路径参数
organizationId
必需
string <uuid>

请求的组织 ID。

userId
必需
string <uuid>

请求用户的ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}

列出所有邀请

返回所有组织邀请的列表。

路径参数
organizationId
必需
string <uuid>

请求的组织 ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": [
    ]
}

创建邀请

创建组织邀请。

路径参数
organizationId
必需
string <uuid>

要邀请用户的组织的ID。

请求体模式：application/json
email
字符串 <电子邮件>

受邀用户的电子邮件地址。只有拥有此电子邮件地址的用户才能使用邀请加入。电子邮件地址以小写形式存储。

role
string
枚举： "admin" "developer"

成员在组织中的角色。

响应

请求示例

内容类型
application/json
{}

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

获取邀请详情

返回单个组织邀请的详细信息。

路径参数
organizationId
必需
string <uuid>

请求的组织 ID。

invitationId
必需
string <uuid>

请求的组织 ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

删除组织邀请

删除单个组织邀请。

路径参数
organizationId
必需
string <uuid>

拥有邀请的组织的ID。

invitationId
必需
string <uuid>

请求的组织 ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}

组织活动列表

返回所有组织活动的列表。

路径参数
organizationId
必需
string <uuid>

请求的组织 ID。

查询参数
from_date
字符串 <日期时间>

搜索的开始日期

to_date
字符串 <日期时间>

搜索的结束日期

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": [
    ]
}

组织活动

根据ID返回单个组织活动。

路径参数
organizationId
必需
string <uuid>

请求的组织 ID。

activityId
必需
string

请求活动的ID。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

获取组织在云提供商内某个区域的私有端点配置

设置私有端点所需的信息

路径参数
organizationId
必需
string <uuid>

请求的组织 ID。

查询参数
云提供商标识符
必需
string

云提供商标识符。可以是 aws、gcp 或 azure 中的其中之一。

云提供商区域
必需
string

特定云提供商内的区域标识符。

响应

响应示例

内容类型
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}