> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickHouse Cloud API

> 了解 ClickHouse Cloud API

<div id="overview">
  ## 概述
</div>

ClickHouse Cloud API 是一个面向开发者的 REST API，旨在让您轻松管理 ClickHouse Cloud 上的组织和服务。通过我们的 Cloud API，您可以创建和管理服务、配置 API 密钥，以及在组织中添加或移除成员等。

[了解如何创建您的第一个 API 密钥，并开始使用 ClickHouse Cloud API。](/zh/products/cloud/features/admin-features/api/openapi)

<div id="swagger-openapi-endpoint-and-ui">
  ## Swagger (OpenAPI) 端点和 UI
</div>

ClickHouse Cloud API 基于开源的 [OpenAPI 规范](https://www.openapis.org/) 构建，
便于客户端以可预测的方式进行调用。如果你需要以编程方式
获取 ClickHouse Cloud API 文档，我们通过 [https://api.clickhouse.cloud/v1](https://api.clickhouse.cloud/v1)
提供基于 JSON 的 Swagger 端点。你也可以通过
[Swagger UI](/zh/products/cloud/api-reference/organization/get-list-of-available-organizations) 查看 API 文档。

<Note>
  如果你的组织已迁移到某个[新定价方案](https://clickhouse.com/pricing?plan=scale\&provider=aws\&region=us-east-1\&hours=8\&storageCompressed=false)，并且你使用 OpenAPI，则需要在创建服务的 `POST` 请求中移除 `tier` 字段。

  由于我们不再提供服务层级，服务对象中的 `tier` 字段已被移除。
  这会影响 `POST`、`GET` 和 `PATCH` 服务请求返回的对象。因此，任何使用这些 API 的代码都可能需要进行相应调整，以适配这些变更。
</Note>

<div id="rate-limits">
  ## 速率限制
</div>

每个组织最多可创建 100 个 API 密钥。每个 API 密钥在
10 秒时间窗口内最多可发出 10 个请求。如果你希望提高组织的
API 密钥数量上限，或提高每 10 秒时间窗口内的请求上限，
请联系 [support@clickhouse.com](mailto:support@clickhouse.com)

<div id="terraform-provider">
  ## Terraform 提供商
</div>

官方的 ClickHouse Terraform 提供商 让您能够使用 [Infrastructure as Code](https://www.redhat.com/en/topics/automation/what-is-infrastructure-as-code-iac)
创建可预测、可进行版本控制的配置，从而大幅降低部署
出错的可能性。

您可以在 [Terraform registry](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs) 中查看 Terraform 提供商 文档。

如果您想为 ClickHouse Terraform 提供商 做出贡献，可以在
[GitHub 仓库](https://github.com/ClickHouse/terraform-provider-clickhouse)中查看源代码。

<Note>
  如果您的组织已迁移到某个[新定价方案](https://clickhouse.com/pricing?plan=scale\&provider=aws\&region=us-east-1\&hours=8\&storageCompressed=false)，则必须使用 2.0.0 或更高版本的 [ClickHouse Terraform 提供商](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs)。必须进行此升级，是因为需要处理服务资源中 `tier` 属性的变更：完成定价迁移后，将不再接受 `tier` 字段，因此应移除对它的引用。

  现在，您还可以将 `num_replicas` 字段指定为服务资源的一个属性。
</Note>

<div id="terraform-provider-releases">
  ## Terraform 提供商 发行版
</div>

ClickHouse 维护着两个官方 Terraform 提供商：用于云基础设施的 ClickHouse Cloud 提供商，以及用于数据库级对象的 DBops 提供商。两者都遵循相同的发布模式。

<div id="ga-vs-beta-resources">
  ### GA 与 Beta 资源
</div>

每个发行版都是一个包含所有资源的构建。尚未达到正式可用阶段的功能所对应的资源会与 GA 资源一同发布，并标记为 **beta**——无需单独的构建，也无需固定版本才能使用它们。

Beta 资源会在以下两处标明：

* **在 plan 和 apply 时**，显示 `Beta Resource` Warning。Terraform 不会因 Warning 而失败，因此运行会正常继续。
* **在其文档中**，会有“此资源处于 beta 阶段”的提示框。

Beta 表示 schema 和行为可能会在未来的提供商版本中发生变化。未带此标记的资源均为 GA，并享有常规的兼容性保证。

<Note>
  在 v3.25.2 之前，提供商将这些资源标记为 *alpha* 而非 *beta*，且 plan 阶段的 Warning 为 `Alpha Resource`。仅措辞发生了变化——不涉及 schema、行为或状态迁移——但通过 grep 在 plan 输出中查找 `Alpha Resource` 的工具将悄然不再匹配。更早的发行版还发布过单独的 alpha 构建。
</Note>

<div id="versioning">
  ### 版本编号
</div>

两个提供商都采用语义化版本控制 (MAJOR.MINOR.PATCH) 。主版本号在发生破坏性变更时递增，次版本号用于新增功能或资源，补丁版本号则用于错误修复。发行版按需进行，而不是按固定周期安排。

带有 `-alphaN` 后缀的版本 (例如 `3.15.0-alpha3`) 早于单一构建模型。它们仍然可用，但不再构建。

<div id="promotion">
  ### 从 Beta 升级为 GA
</div>

当某项功能达到正式可用状态后，其资源会在下一个提供商发行版中移除 Beta 标记：plan 时 Warning 不再显示，文档中的提示框也会被移除。其他方面均不会改变——无需修改配置、状态迁移，也无需在不同构建之间切换。

<div id="terraform-and-openapi-new-pricing---replica-settings-explained">
  ## Terraform 和 OpenAPI 新定价：副本设置说明
</div>

每个服务在创建时的默认副本数，在 Scale 和 Enterprise 层级中为 3，而在基础版中为 1。
对于 Scale 和 Enterprise 层级，可以通过在服务创建请求中传入 `numReplicas` 字段来调整副本数。
对于仓库中的第一个服务，`numReplicas` 字段的值必须在 2 到 20 之间。在现有仓库中创建的服务，副本数则最低可为 1。

<div id="support">
  ## 支持
</div>

我们建议您先访问[我们的 Slack 频道](https://clickhouse.com/slack)，以获得快速支持。如果
您需要更多帮助，或想进一步了解我们的 API 及其功能，
请通过 [https://console.clickhouse.cloud/support](https://console.clickhouse.cloud/support) 联系 ClickHouse 支持团队