文档中心

消息队列 Kafka版

Topic 管理

CreateTopic - 创建 Topic

调用 CreateTopic 接口创建 Kafka Topic。

使用说明

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

说明

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

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下方仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

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 的分区数之和不超过该实例的分区数上限。如果分区数无法满足业务需求，您可以购买更多分区，提升实例的分区数量上限。详细说明请参考升级实例规格。

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 参数说明。您也可以通过文档修改参数配置查看各参数的详细信息。

通过 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 消息清理策略。

返回参数

本接口无特有的返回参数。更多信息请见返回结构。

请求示例

返回示例

错误码

下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见公共错误码文档。

状态码	错误码	错误信息	说明
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.	服务繁忙，请稍后重试。

最近更新时间：2026.06.15 16:34:18

这个页面对您有帮助吗？

有用

无用