CreateTopic - 创建 Topic--消息队列 Kafka版-火山引擎

文档中心

立即注册

导航

CreateTopic - 创建 Topic

最近更新时间：2024.09.27 10:59:00首次发布时间：2023.03.30 19:59:25

调用 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-cnngbnnts1****	实例 ID。
TopicName	String	是	my_topic	待创建的 Topic 名称。 3～64 个字符。必须以英文或数字开头。支持的字符包括英文、数字、连字符（-）、下划线（_）和英文句号（.）。
PartitionNumber	Integer	是	12	Topic 分区数。取值范围为 1~300，如果实例中已创建了其他 Topic，则所有 Topic 的分区数之和不超过该实例的分区数上限。如果分区数无法满足业务需求，您可以购买更多分区，提升实例的分区数量上限。详细说明请参考升级实例规格。
AllAuthority	Boolean	否	true	待创建的Topic默认是否对所有用户都开启读写权限。 true：（默认）所有用户都具备此 Topic 的读写权限。 false：并非所有用户都具备此 Topic 的读写权限。默认情况下，用户对于此 Topic 的权限沿用用户的默认权限，如果默认权限不满足需求，您也可以通过 AccessPolicies 指定某个用户对于此 Topic 的自定义权限。
ReplicaNumber	Integer	否	3	Topic 副本个数。可设置为为 2 或 3，默认值为 3。
Description	String	否	描述信息	Topic 的描述信息。长度不超过 128 个字符。
Parameters	String	否	{"MessageMaxByte":"11"}	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 天。默认沿用实例的消息保留时长设置。
AccessPolicies	Array of Object	否	--	自定义权限配置，即为某些用户设置对于此 Topic 的自定义权限。仅在 AllAuthority 为 False 时需要设置。
Tags	Array of Object	否	--	云资源标签。可以将 Topic 通过标签进行归类，便于 Topic 的识别和管理。标签设置规则请参见标签设置规则。
CleanupPolicy	Array of String	否	["delete"]	Topic 的消息清理策略，支持以下三种取值方式： ["delete"]：默认的消息清理策略。在磁盘容量充足的情况下，保留在最长保留时间范围内的消息；在磁盘容量不足时，将提前删除旧消息，以保证服务可用性。说明说明 Kafka 实例默认的磁盘清理水位为 90%，具体以实际为准，详情请参见设置磁盘清理水位。 ["compact"]：COMPACT 消息清理策略针对每个消息的 Key 进行整合，对于有相同 Key 的消息，只保留最新的 value 值，旧的记录则会被清除。 ["delete","compact"]：同时配置 DELETE 和 COMPACT 两种消息清理策略。只要消息满足任一条清理策略时，都将被清除。说明如果消息没有 Key，不支持启用 COMPACT 消息清理策略。

返回参数

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

请求示例

POST /?Action=CreateTopic&Version=2022-05-01 HTTP/1.1
Content-Type: application/json
Host: kafka.volcengineapi.com
X-Date: 20210328T100802Z
Authorization: HMAC-SHA256 Credential=AK********/20210328/cn-beijing/Kafka/request, SignedHeaders=x-date, Signature=********

{
  "InstanceId": "kafka-cnngbnntswg1****",
  "TopicName": "my_topic3",
  "PartitionNumber": 12,
  "AllAuthority": false,
  "AccessPolicies":[{"UserName":"user123","AccessPolicy":"PubSub"}],
  "Description":"123",
  "ReplicaNumber":3,
  "Parameters":"{\"LogRetentionHours\":\"72\",\"MessageMaxByte\":\"10\",\"MinInsyncReplicaNumber\":\"2\"}"
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "2023022719194098F0DF73611FD95FA1A2",
        "Action": "CreateTopic",
        "Version": "2022-05-01",
        "Service": "Kafka",
        "Region": "cn-beijing"
    },
    "Result": null
}

错误码

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

状态码	错误码	错误信息	说明
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数量超出上限。
500	ServiceBusy	The service is busy. Try again later.	服务繁忙，请稍后重试。