创建 Topic

Topic（消息主题）是同一种类型消息的集合，是消息队列 Kafka版中数据写入操作的基本单元。本文档介绍创建单个 Topic 的操作步骤。

背景信息

在实际业务场景中，一个 Topic 常被用作承载同一种业务流量，由开发者根据自身系统设计、数据架构设计来决定如何设计不同的 Topic。每个 Topic 可以有多个生产者向它发送消息，也可以有多个消费者去消费其中的消息。
分区（Patition）是 Topic 在物理上的分组，每个 Topic 可以划分为多个分区，每个分区都是一个有序的队列。创建 Topic 时需要指定分区数量，但是随着业务流量的增长，也可以随时增加 Topic 的分区，扩展 Topic 承载业务流量的能力。
消息队列 Kafka版通过自动创建 Topic 的功能控制 Kafka 实例支持的 Topic 创建方式，该功能默认为关闭状态。

• 关闭时，只能通过控制台创建 Topic。
• 开启时，不仅可通过控制台创建 Topic，还可以在生产消息时直接指定数据写入一个不存在的 Topic，此时 Kafka 后端服务会自动为您创建此 Topic。

前提条件

已创建消息队列 Kafka版实例，且实例状态为运行中。详细操作步骤请参考创建实例。

手动创建 Topic

消息队列 Kafka版支持通过控制台或 OpenAPI 的方式手动逐个创建 Topic。

通过控制台创建 Topic

1. 登录消息队列 Kafka版控制台。

2. 在顶部菜单栏中选择地域，并在左侧导航栏中单击实例列表。

3. 找到目标实例，单击实例名称。

4. 在页签栏中单击Topic管理。

5. 单击创建Topic。

6. 填写 Topic 基础配置。

   参数	说明
   Topic名称	Topic 的名称。需要符合以下命名规范： 3～64 个字符。 必须以英文或数字开头。 支持的字符包括英文、数字、连字符（-）、下划线（_）和英文句号（.）。 说明 创建 Topic 之后不支持修改 Topic 名称。
   描述	Topic 的备注信息，可以用于简单描述 Topic 的用途、对应的业务类型等信息。

7. 填写 Topic 参数配置。

   参数	说明
   分区数	此 Topic 的分区数量。分区数量越大，消费的并发度越大。 默认值为 12，取值范围为 1～300。分区数量应为 Broker 数量的整数倍，您可以参考查看节点信息查看当前实例的 Broker 数量。 该参数只能调大不能调小，且不可超过 Kafka 实例的剩余可用分区数。
   副本数	分区的副本个数，表示在对应数量的副本上备份数据，用于保障分区的高可用。当其中一个 Broker 故障时仍可保障数据可用性，副本数越大可靠性越高。 副本数支持设置为 1、2 或 3，默认为 3。 说明 增加副本数会占用实例磁盘容量，请确保容量充足。增加副本时会占用实例带宽资源，建议在业务低峰期操作。 减少副本数会降低数据可用性，请谨慎操作。 1 副本 Topic 无法保障数据可靠性且实例升级期间无法进行读写操作，建议选择 2 副本或 3 副本。
   最小同步副本数	Topic 最小同步副本个数，即 min.insync.replicas 参数。该值越大，数据可靠性越好，但是可用性将会降低。 副本数为 1 时，最小同步副本数只能为 1。 副本数为 2 或 3 时，最小同步副本数不能超过副本数减 1。
   消息保留时长	磁盘容量充足时，消息在此 Topic 中的最大保留时长，即消息的存储时间。消费者必须在此时间结束前消费消息，否则消息将被删除。删除的消息，无法被消费。 单位为小时，取值范围为 0～2160，目前支持的最大存储时长为 90 天。默认为实例级别的消息保留时长，您也可以在此处指定该 Topic 的消息保留时长，仅对该 Topic 生效。
   最大消息大小	此 Topic 中单条消息的最大长度。 取值范围为 1MB～12MB。默认为实例级别的最大消息大小，您也可以在此处指定该 Topic 的最大消息大小，仅对该 Topic 生效。

8. 配置用户权限。
   指定实例内 SASL 用户对该 Topic 的操作权限。
   默认为全部允许，即全部 SASL 用户对于此 Topic 都具备读写权限，即使该用户关闭了 All Permitted 权限。您也可以选择自定义设置，为不同 SASL 用户分别指定权限类型。自定义权限包括：

   • 只读：只具备消息订阅权限，不具备消息生产权限。
   • 只写：只具备消息生产权限，不具备消息订阅权限。
   • 读写：同时具备消息生产和消息订阅权限。

   说明

   • 自定义设置只对关闭了 All Permitted 的 SASL 用户生效。
   • 创建 Topic 时，如果设置了自定义权限，消息队列 Kafka版会同步创建对应的 ACL，并将其显示在 ACL 列表中。创建 Topic 后如果需要修改自定义权限，推荐通过 ACL 操作，详细说明请参考创建 ACL。

9. 配置消息清理策略。

   • DELETE：默认的消息清理策略。在磁盘容量充足的情况下，保留在最长保留时间范围内的消息；在磁盘容量不足时，将提前删除旧消息，以保证服务可用性。

     说明

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

   • COMPACT：COMPACT 消息清理策略针对每个消息的 Key 进行整合，对于有相同 Key 的消息，只保留最新的 value 值，旧的记录则会被清除。

     注意

     如果消息没有 Key，请谨慎启用 COMPACT 消息清理策略。在没有消息 Key 的情况下启用 COMPACT 策略，将会把旧消息都清除掉。

   • DELETE,COMPACT：同时配置 DELETE 和 COMPACT 两种消息清理策略。只要消息满足任一条清理策略时，都将被清除。

10. （可选）配置 Topic 标签。
    单击添加标签，输入标签键和标签值，为 Topic 添加自定义标签。
    标签用于云资源的标识与分类，添加标签有利于识别和管理 Topic。每次支持添加 20 个标签，标签设置规则请参见标签设置规则。

11. 单击确定。
    在Topic管理页签中可以查看已创建好的 Topic。

通过 OpenAPI 创建 Topic

消息队列 Kafka版提供 OpenAPI CreateTopic，用于手动创建 Topic。

自动创建 Topic

使用自动创建 Topic 的功能前，需要先在控制台开启此功能，并通过客户端 SDK 在写入消息时指定一个不存在 Topic。自动创建的 Topic 默认配置如下。

1 开启自动创建 Topic 功能

1. 登录消息队列 Kafka版控制台。

2. 在顶部菜单栏中选择地域，并在左侧导航栏中单击实例列表。

3. 找到目标实例，单击实例名称。

4. 在Topic管理页签中单击设置自动创建 Topic。

5. 开启自动创建Topic开关，并设置以下参数。

   参数	说明
   默认分区数	自动创建的 Topic 的默认分区数量。 取值范围为 1~300，且不可超过实例的剩余可用分区数。
   默认副本数	自动创建的 Topic 的默认分区副本数量。 支持设置为 1 副本、2 副本或 3 副本。

6. 在弹出的对话框中单击确定。

   说明

   对于2023年10月26日及之前创建的实例，设置默认分区数或副本数时，后端服务会自动重启实例以使配置生效。

2 通过 Kafka 客户端 SDK 自动创建 Topic

开启自动创建 Topic 功能后，您可以在生产侧客户端 SDK 中设置一个不存在的 Topic 名称，请求向其写入消息数据。消息队列 Kafka版收到请求时会自动在对应实例中创建此 Topic。
您可以参考以下 Java 语言的示例代码在 Kafka 客户端 SDK 中为生产者实例设置消息写入的 Topic，也可以参考消息队列 Kafka版提供的示例项目，编写相关业务逻辑。

......
    // 设置一个不存在的 Topic 名称，后端服务收到请求后会自动创建此 Topic
    private void setTopic(Properties kafkaProperties) {
        topic  = kafkaProperties.getProperty("topic");
    }
    ......

相关操作

创建 Topic 后，您可以根据需求随时修改 Topic 的配置及用户权限，也可以查看 Topic 的详细信息。

• 修改 Topic 配置：支持修改 Topic 的分区数、副本数、最小同步副本数、消息保留时长、最大消息大小，详细信息请参考修改Topic配置。
• 管理 Topic 标签：支持根据标签筛选 Topic；还支持批量绑定标签和解绑标签。详细信息请参考管理 Topic 标签。
• 修改用户权限：通过 ACL 设置 SASL 用户对于此 Topic 的权限，详细信息请参考创建 ACL。
• 查看 Topic 和分区详情：查看 Topic 的状态、分区数等信息，详细信息请参考查看Topic和分区详情。
• 导出 Topic 列表：通过控制台导出 Topic 列表，其中包括 Topic 的名称、副本数等设置，详细信息请参考导出 Topic 列表。
• 删除 Topic：不再使用某个 Topic 时，建议及时删除以节约资源。详细信息请参考删除 Topic。