CreateTopic - 创建topic--消息队列 RocketMQ版-火山引擎

文档中心

导航

CreateTopic - 创建topic

最近更新时间：2024.11.18 10:27:31首次发布时间：2023.07.12 16:22:34

调用 CreateTopic 接口创建 Topic。

使用说明

在RocketMQ 实例中，Topic 是消息发送与接收的基本单元，消息队列 RocketMQ版通过 Topic 对各类消息进行分类管理。消息的生产者将消息发送到 RocketMQ Topic 中，而消息的消费者则通过订阅该 RocketMQ Topic 来消费消息。

说明

每个实例的 Topic 数量配额与实例规格有关，例如各个规格实例可创建的 Topic 数量请参考产品规格。

注意事项

请求频率：该接口请求频率限制为 100 次/秒；单用户请求频率限制为 20 次/秒。

调试

API Explorer

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

去调试

请求参数

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

参数	类型	是否必填	示例值	描述
Action	String	是	CreateTopic	要执行的操作，取值：CreateTopic。
Version	String	是	2023-01-01	API的版本，取值：2023-01-01。
QueueNumber	Integer	是	12	设置当前 Topic 的队列数量，最大不可超过当前实例剩余可用队列数。每个实例规格的队列数量限制请参考产品规格。在 4.x 版本实例中创建 Topic 时，请参考以下说明设置队列数：全局顺序类型的 Topic 队列数默认为 1。其他类型 Topic 的队列数和计算规格有关，n3 及以下规格的队列数默认为 6，n3 以上规格的队列数默认是 broker 组数的两倍。队列数建议设置为计算节点数的倍数，否则可能造成不同 Broker 之间数据不均衡。例如规格 rocketmq.n3.x2.medium 的计算节点数为 3，队列数建议设置为 3 的倍数，即 3、6、9 等。在 5.x 版本实例中创建 Topic 时，请参考以下说明设置队列数：全局顺序类型的 Topic 队列数默认为 1。其他类型 Topic 的队列数默认是 broker 组数的两倍。非顺序场景性能不受队列个数影响，更多队列仅用于提升顺序消费并发性能。
MessageType	Integer	是	0	消息类型。取值说明如下： 0：普通消息 1：事务消息 2：分区顺序消息 3：全局顺序消息 4：延时消息说明一个 Topic 只能承载一种消息类型。创建 Topic 后不支持修改此 Topic 承载的消息类型。对于分区顺序消息和全局顺序消息类型的 Topic，服务节点异常时可能会出现短暂的消息乱序现象。延迟消息支持自定义毫秒级延迟，延迟时长最长为 3 天或消息保留时长的 3 倍（两者取较小值）。
AccessPolicies	Array of Object	否	/	每个 RocketMQ 密钥对于当前 Topic 的权限，支持批量设置权限。若未设置，每个密钥对于当前 Topic 维持密钥的默认权限。
Description	String	否	this is a test topic	Topic 的描述信息，长度为 0~128 个字符。
InstanceId	String	是	rocketmq-cnai1f0c29ca****	实例 ID。
TopicName	String	是	my_topic	Topic 的名称。命名规则如下：长度为 3~100 个字符。只能包含英文、数字、连字符（-）以及下划线（_）。 Topic 名称中不可包含以下保留字符或特殊前缀。保留字符：RMQ_SYS_TRANS_OP_HALF_TOPIC、BenchmarkTest、TBW102、OFFSET_MOVED_EVENT、SELF_TEST_TOPIC、RMQ_SYS_TRANS_HALF_TOPIC、SCHEDULE_TOPIC_XXXX、RMQ_SYS_TRACE_TOPIC 特殊前缀：rocketmq-broker-、%RETRY%、rmq_sys_、%DLQ% 说明同一实例下 Topic 名称必须唯一，不同实例间的 Topic 名称可以重复。对于2023年6月5日及之前创建的 RocketMQ 实例，Topic 名称不可超过 100 个字符。

返回参数

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

请求示例

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

{
  "InstanceId": "rocketmq-cnai1f0c29ca****",
  "TopicName": "rocketmq123",
  "QueueNumber": 10,
  "MessageType": 0,
  "Description": "test",
  "AccessPolicies": [
      {
        "AccessKey":"2QdEgrGc97AL1p38Fq13****",
        "Authority": "ALL"
      }
  ]
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "2023022719194098F0DF73611FD95FA1A2",
        "Action": "CreateTopic",
        "Version": "2023-01-01",
        "Service": "RocketMQ",
        "Region": "cn-shanghai"
    },
    "Result": null
}

错误码

公共错误码请参见公共错误码文档。