You need to enable JavaScript to run this app.
导航

创建 Topic

最近更新时间2023.11.24 10:44:22

首次发布时间2021.08.30 16:20:22

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

背景信息

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

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

说明

每个规格的实例均提供一定额度的分区数量范围与免费分区数,如果免费分区额度已用完,则必须购买分区后才能继续创建 Topic 或扩分区。如果分区数量已达该规格的最大额度,则只能调整分区规格、获得更大的分区额度才能继续创建 Topic 或扩分区。

前提条件

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

手动创建 Topic

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

说明

  • 成功创建 Topic 之后,不支持修改 Topic 名称,且分区数量只能调大、不能调小,创建或修改时请合理规划分区数量。
  • 在应用迁移上云或实例备份等场景下,如果需要一次性创建多个 Topic,可以通过上传配置文件的方式批量创建 Topic,操作步骤可参考批量导入 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. 单击确定
    Topic管理页签中可以查看已创建好的 Topic。

通过 OpenAPI 创建 Topic

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

自动创建 Topic

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

参数

默认配置

Topic 名称

默认使用客户端 SDK 指定的 Topic 名称。应符合以下规范:

  • 3~64 个字符。
  • 必须以英文或数字开头。
  • 支持的字符包括英文、数字、连字符(-)、下划线(_)和英文句号(.)。

说明

  • 不可以 __ 开头,否则自动创建 Topic 失败。
  • 如果 Topic 名称中指定了不符合规范的字符,则可能出现无法采集 Topic 监控数据等问题。

描述

无。

分区数

开启自动创建 Topic 功能时设置的默认分区数

副本数

开启自动创建 Topic 功能时设置的默认副本数

最小同步副本数

默认为 1。

消息保留时长

默认沿用实例的消息保留时长。

最大消息大小

默认沿用实例的最大消息大小。

用户权限

默认此 Topic 无任何自定义权限。如果开启了 ACL,则权限为 All Permitted 的 SASL 用户才具备此 Topic 的读写权限。

说明

  • 建议您仅在接入测试或数据迁移场景下使用自动创建 Topic 的功能。在实际的生产环境中,尤其是对性能和稳定性要求比较高的核心生产业务中建议关闭该功能。
  • 相较于手动创建 Topic,自动创建 Topic 耗时更高,且成功创建 2 分钟后才会显示在 Topic 列表中。
  • 实例更配过程中,禁止通过任何方式创建 Topic。通过客户端创建 Topic 之前,请确认实例状态为运行中(Running)。

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配置
  • 修改用户权限:通过 ACL 设置 SASL 用户对于此 Topic 的权限,详细信息请参考创建 ACL
  • 查看 Topic 和分区详情:查看 Topic 的状态、分区数等信息,详细信息请参考查看Topic和分区详情
  • 导出 Topic 列表:通过控制台导出 Topic 列表,其中包括 Topic 的名称、副本数等设置,详细信息请参考导出 Topic 列表
  • 删除 Topic:不再使用某个 Topic 时,建议及时删除以节约资源。详细信息请参考删除 Topic