调用 CreateTopic 接口创建 Kafka Topic。 ## 使用说明此接口用于在指定实例下创建一个 Kafka 的 Topic，用户可使用该 Topic 发布和订阅消息。

说明

实例更配过程中，禁止通过任何方式创建 Topic。创建 Topic 之前，请确认实例状态为运行中（Running）。

## 调试 [去调试](https://api.volcengine.com/api-explorer/?action=CreateTopic&groupName=Topic%20%E7%AE%A1%E7%90%86&serviceCode=Kafka&version=2022-05-01) ## 请求参数下方仅列出该接口特有的请求参数和部分公共参数。更多信息请见[公共参数](https://www.volcengine.com/docs/6369/67268)。 **Action** string 必选 `示例值：CreateTopic` 要执行的操作，取值：CreateTopic。 **Version** string 必选 `示例值：2022-05-01` API 的版本，取值：2022\-05\-01。 **InstanceId** string 必选 `示例值：kafka-cnngc7an0qpv****` 实例 ID。 **TopicName** string 必选 `示例值：test-topic` 待创建的 Topic 名称。 * 3~249 个字符。 * 必须以英文或数字开头。 * 支持的字符包括英文、数字、连字符（\-）、下划线（_）和英文句号（.）。 **Description** string `可选` `示例值：This is the description of a topic.` Topic 的描述信息。长度不超过 128 个字符。 **PartitionNumber** integer 必选 `示例值：12` 单个 Topic 可创建的分区数量。取值范围为 1~300，如果实例中已创建了其他 Topic，则所有 Topic 的分区数之和不超过该实例的分区数上限。如果分区数无法满足业务需求，您可以购买更多分区，提升实例的分区数量上限。详细说明请参考[升级实例规格](https://www.volcengine.com/docs/6439/107364?)。 **ReplicaNumber** integer 必选 `示例值：3` 分区的副本个数，上限值为 3。 **AllAuthority** boolean `可选` `示例值：true` 待创建的 Topic 是否对所有用户开启读写权限。 * true：（默认）所有用户都具备此 Topic 读写权限。 * false：并非所有用户都具备此 Topic 的读写权限。默认情况下，用户对于此 Topic 的权限沿用用户的默认权限，如果默认权限不满足需求，您也可以通过 AccessPolicies 指定某个用户对于此 Topic 的自定义权限。 **AccessPolicies** object[] `可选` `示例值：Sub` 自定义权限配置，即为某些用户设置对于此 Topic 的自定义权限。仅在 AllAuthority 为 False 时需要设置。 **UserName** string 必选 `示例值：test` SASL 用户名称。 **AccessPolicy** string 必选 `示例值：Sub` SASL 用户对于当前 Topic 的访问权限。 * PubSub：拥有发布、订阅权限。 * Pub：拥有发布权限。 * Sub：拥有订阅权限。 **Parameters** string `可选` `示例值：{"MessageMaxByte":"12"}` Topic 级别的参数配置。当前支持的参数列表及参数默认值，请参考 Topic Parameters 参数说明。您也可以通过文档[修改参数配置](https://www.volcengine.com/docs/6439/102156)查看各参数的详细信息。通过 Postman 等方式调用 API 时，应注意转义，例如`{\"LogRetentionHours\":\"72\",\"MessageMaxByte\":\"10\",\"MinInsyncReplicaNumber\":\"2\"}`。 Parameters 参数说明： * `"MinInsyncReplicaNumber":"2"`：最小同步副本个数。当同步副本个数小于配置值时，消息将无法写入对应 Topic。配置值越大，数据可靠性增加，但是可用性将会降低。默认值为副本数减 1。考虑到 Topic 的可用性，建议设置为副本数减 1。 * `"MessageMaxByte":"12"`：最大消息大小。单位为 MB，取值范围为 1～12。默认沿用实例的最大消息大小设置。 * `"LogRetentionHours":"72"`：消息保留时长。单位为小时，取值范围为 0～2160，即消息最久保留 90 天。默认沿用实例的消息保留时长设置。 **Tags** object[] `可选` `示例值：--` 云资源标签。可以将 Topic 通过标签进行归类，便于 Topic 的识别和管理。标签设置规则请参见标签设置规则。 **Key** string 必选 `示例值：test-key` 标签的键。 **Value** string 必选 `示例值：test-value` 标签的值。 **CleanupPolicy** string[] `可选` `示例值：delete` 消息清理策略。 Topic 的消息清理策略，支持以下三种取值方式： * ["delete"]：默认的消息清理策略。在磁盘容量充足的情况下，保留在最长保留时间范围内的消息；在磁盘容量不足时，将提前删除旧消息，以保证服务可用性。说明

说明

Kafka 实例默认的磁盘清理水位为 90%，具体以实际为准，详情请参见设置磁盘清理水位。

* ["compact"]：COMPACT 消息清理策略针对每个消息的 Key 进行整合，对于有相同 Key 的消息，只保留最新的 value 值，旧的记录则会被清除。 * ["delete","compact"]：同时配置 DELETE 和 COMPACT 两种消息清理策略。只要消息满足任一条清理策略时，都将被清除。

说明

如果消息没有 Key，不支持启用 COMPACT 消息清理策略。

## 返回参数本接口无特有的返回参数。更多信息请见[返回结构](https://www.volcengine.com/docs/6369/80336)。 ## 请求示例 ```json POST /?Action=CreateTopic&Version=2022-05-01 HTTP/1.1 Host: kafka.cn-beijing.volcengineapi.com Content-Type: application/json; charset=UTF-8 X-Date: 20260615T064738Z X-Content-Sha256: 287e874e******d653b44d21e Authorization: HMAC-SHA256 Credential=Adfks******wekfwe/20260615/cn-beijing/Kafka/request, SignedHeaders=host;x-content-sha256;x-date, Signature=47a7d934ff7b37c03938******cd7b8278a40a1057690c401e92246a0e41085f { "InstanceId": "kafka-cnngc7an0qpv****", "TopicName": "test-topic", "Description": "This is the description of a topic.", "PartitionNumber": 12, "ReplicaNumber": 3, "AllAuthority": true, "AccessPolicies": [ { "UserName": "test", "AccessPolicy": "Sub" } ], "Parameters": "\"MessageMaxByte\":\"12\"", "Tags": [ { "Key": "test-key", "Value": "test-value" } ], "CleanupPolicy": [ "delete" ] } ``` ## 返回示例 ```json { "ResponseMetadata": { "RequestId": "2026061514525214***6140F85148", "Action": "CreateTopic", "Version": "2022-05-01", "Service": "Kafka", "Region": "cn-beijing" }, "Result": {} } ``` ## 错误码下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见[公共错误码](https://www.volcengine.com/docs/6369/68677)文档。 |状态码 |错误码 |错误信息 |说明 | |---|---|---|---| |400 |OperationDenied.InvalidRequest |The request that you specified is not valid. |请求异常，请检查后重试。 | |400 |InvalidTopicName.AlreadyExists |The specified topic name already exists. |Topic 名称已存在。 | |400 |QuotaExceeded.TopicNumber |The number of topic exceeds the limit. |Topic 数量超出上限。 | |400 |InvalidParameter.instance.id:kafka\-cng2fb4ucoghof51 |The specified parameter instance_id:kafka\-cng2fb4ucoghof51 is not valid. |实例 ID 参数非法。 | |404 |InvalidInstanceId.NotFound |The specified Instance ID does not exist. |实例不存在。 | |500 |ServiceBusy |The service is busy. Try again later. |服务繁忙，请稍后重试。 |

消息队列 Kafka版