本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 主题操作 您可以使用 Amazon MSK APIs 管理您的 MSK 预配置集群中的主题，而无需设置和维护 Kafka 管理员客户端。有了这些 APIs，您可以定义或读取主题属性，例如复制因子和分区计数，以及保留和清理策略等配置设置。您可以使用熟悉的界面（包括 CL AWS I、 AWS SDKs和）以编程方式管理 Kafka 主题。 AWS CloudFormation APIs 它们还集成到 Amazon MSK 控制台中，将所有主题操作集中到一个地方。现在，您只需点击几下即可使用引导式默认设置创建或更新主题，同时全面了解主题配置、分区级信息和指标。 **重要** 这些主题 API 响应反映的数据大约每分钟更新一次。要了解更改后的最新主题状态，请在查询前等待大约一分钟。 ## 使用主题的要求 APIs + 您的集群必须是 MSK 预配置的集群。 APIs 这些不适用于 MSK 无服务器集群。 + 您的集群必须运行 Apache Kafka 版本 3.6.0 或更高版本。有关支持的版本的更多信息，请参阅[支持的 Apache Kafka 版本](supported-kafka-versions.md)。 + 您的集群必须处于`ACTIVE`状态。有关集群状态的更多信息，请参阅[了解预置 MSK 集群状态](msk-cluster-states.md)。 + 您必须拥有相应的 IAM 权限。有关更多信息，请参阅 [用于主题操作的 IAM 权限 APIs](#topic-operations-permissions)。 ## 用于主题操作的 IAM 权限 APIs 要调用它们 APIs，您必须拥有相应的 IAM 权限。下表列出了每个 API 所需的权限。 **主题操作所需的权限 APIs** | API | 所需权限 | 资源 | | --- | --- | --- | | ListTopics | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` | 集群 ARN，主题 ARN | | DescribeTopic | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` `kafka-cluster:DescribeTopicDynamicConfiguration` | 集群 ARN，主题 ARN | | DescribeTopicPartitions | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` `kafka-cluster:DescribeTopicDynamicConfiguration` | 集群 ARN，主题 ARN | | CreateTopic | `kafka-cluster:Connect` `kafka-cluster:CreateTopic` | 集群 ARN，主题 ARN | | DeleteTopic | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` `kafka-cluster:DeleteTopic` | 集群 ARN，主题 ARN | | UpdateTopic | `kafka-cluster:Connect` `kafka-cluster:DescribeTopic` `kafka-cluster:AlterTopic` `kafka-cluster:AlterTopicDynamicConfiguration` | 集群 ARN，主题 ARN | **注意** 对于`kafka-cluster:Connect`，请在您的 IAM 策略中指定集群 ARN。对于所有其他操作，请在您的 IAM 策略中指定主题 ARN。 **注意** 对于`ListTopics`，您可以使用通配符 (\$1) 来匹配集群上的所有主题。例如：`arn:aws:kafka:us-east-1:123456789012:topic/my-cluster/abcd1234-abcd-dcba-4321-a1b2abcd9f9f-2/*`。 有关适用于 Amazon MSK 的 IAM 访问控制的更多信息，请参阅[IAM 访问控制](iam-access-control.md)。 **Topics** + [使用主题的要求 APIs](#topic-operations-requirements) + [用于主题操作的 IAM 权限 APIs](#topic-operations-permissions) + [在 Amazon MSK 集群中列出主题](msk-list-topics.md) + [获取有关某个主题的详细信息](msk-describe-topic.md) + [查看主题的分区信息](msk-describe-topic-partitions.md) + [在 Amazon MSK 集群中创建主题](msk-create-topic.md) + [更新 Amazon MSK 集群中的主题](msk-update-topic.md) + [删除 Amazon MSK 集群中的主题](msk-delete-topic.md) # 在 Amazon MSK 集群中列出主题 您可以列出 MSK Provisioned 集群中的所有主题，以查看基本元数据，例如分区计数和复制因子。这对于监控集群的主题、执行库存检查或确定需要进一步调查的主题非常有用。 **注意** `ListTopics`API 提供基本的主题元数据。要获取有关特定主题的详细信息，包括其当前状态和配置，请使用 `DescribeTopic` API。有关更多信息，请参阅 [获取有关某个主题的详细信息](msk-describe-topic.md)。 **注意** 此 API 响应反映了大约每分钟更新一次的数据。要了解更改后的最新主题状态，请在查询前等待大约一分钟。 **Topics** + [使用列出主题 AWS 管理控制台](list-topics-console.md) + [使用列出主题 AWS CLI](list-topics-cli.md) + [使用 API 列出主题](list-topics-api.md) # 使用列出主题 AWS 管理控制台 1. 登录并在[https://console.aws.amazon.com/msk/家中打开 Amazon MSK 控制台？ AWS 管理控制台 region=us](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)-east-1\$1/home/。 1. 在集群列表中，选择要列出其主题的集群的名称。 1. 在集群详细信息页面上，选择**主题**选项卡。 1. 该表显示了集群中的所有主题，包括主题名称、分区数、重复因子和 out-of-sync副本数。 # 使用列出主题 AWS CLI 运行以下命令，*ClusterArn*替换为集群的 Amazon 资源名称 (ARN)。如果您没有该集群的 ARN，可以通过列出所有集群来找到它。有关更多信息，请参阅 [列出 Amazon MSK 集群](msk-list-clusters.md)。 ``` aws kafka list-topics --cluster-arn ClusterArn ``` 该 命令的输出如以下 JSON 示例所示。 ``` { "topics": [ { "topicArn": "arn:aws:kafka:us-east-1:123456789012:topic/MyCluster/abcd1234-abcd-dcba-4321-a1b2abcd9f9f-2/MyTopic", "topicName": "MyTopic", "partitionCount": 3, "replicationFactor": 3, "outOfSyncReplicaCount": 0 }, { "topicArn": "arn:aws:kafka:us-east-1:123456789012:topic/MyCluster/abcd1234-abcd-dcba-4321-a1b2abcd9f9f-2/AnotherTopic", "topicName": "AnotherTopic", "partitionCount": 6, "replicationFactor": 3, "outOfSyncReplicaCount": 1 } ] } ``` ## 对结果进行分页 如果您的集群有许多主题，则可以使用分页功能以较小的批量检索结果。使用`--max-results`参数指定要返回的最大主题数，并使用`--next-token`参数检索下一页的结果。 ``` aws kafka list-topics --cluster-arn ClusterArn --max-results 10 ``` 如果有更多结果可用，则响应中会包含一个`nextToken`值。使用此令牌检索下一页的结果。 ``` aws kafka list-topics --cluster-arn ClusterArn --max-results 10 --next-token NextToken ``` ## 按名称筛选主题 您可以通过使用`--topic-name-filter`参数指定前缀来筛选主题列表。这将仅返回名称以指定前缀开头的主题。 ``` aws kafka list-topics --cluster-arn ClusterArn --topic-name-filter "prod-" ``` 此命令仅返回名称以开头的主题`prod-`，例如`prod-orders`或`prod-inventory`。 # 使用 API 列出主题 要使用 API 列出主题，请参阅[ListTopics](https://docs.aws.amazon.com//msk/1.0/apireference/v1-clusters-clusterarn-topics.html#ListTopics)。 # 获取有关某个主题的详细信息 您可以检索有关 MSK Provisioned 集群中特定主题的详细信息，包括其当前状态、分区数、重复因子和配置。这对于故障排除、验证主题设置或在操作期间监控主题状态非常有用。 **注意** 此 API 响应反映了大约每分钟更新一次的数据。要了解更改后的最新主题状态，请在查询前等待大约一分钟。 **Topics** + [使用描述主题 AWS 管理控制台](describe-topic-console.md) + [使用描述主题 AWS CLI](describe-topic-cli.md) + [使用 API 描述主题](describe-topic-api.md) # 使用描述主题 AWS 管理控制台 1. 登录并在[https://console.aws.amazon.com/msk/家中打开 Amazon MSK 控制台？ AWS 管理控制台 region=us](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)-east-1\$1/home/。 1. 在集群列表中，选择包含您要描述的主题的集群的名称。 1. 在集群详细信息页面上，选择**主题**选项卡。 1. 在主题列表中，选择要查看的主题的名称。 1. 主题详细信息页面显示有关该主题的信息，包括其状态、分区数、重复因子和配置设置。 # 使用描述主题 AWS CLI 运行以下命令，*ClusterArn*替换为集群的 Amazon 资源名称 (ARN) 和*TopicName*您要描述的主题的名称。 ``` aws kafka describe-topic --cluster-arn ClusterArn --topic-name TopicName ``` 该 命令的输出如以下 JSON 示例所示。 ``` { "topicArn": "arn:aws:kafka:us-east-1:123456789012:topic/MyCluster/abcd1234-abcd-dcba-4321-a1b2abcd9f9f-2/MyTopic", "topicName": "MyTopic", "partitionCount": 3, "replicationFactor": 3, "configs": "Y29tcHJlc3Npb24udHlwZT1wcm9kdWNlcgpyZXRlbnRpb24ubXM9NjA0ODAwMDAw", "status": "ACTIVE" } ``` ## 了解主题状态 该`status`字段表示主题的当前状态。下表描述了可能的状态值。 **主题状态值** | Status | 说明 | | --- | --- | | CREATING | 主题正在创建中。 | | ACTIVE | 该主题处于活动状态，可供使用。 | | UPDATING | 主题配置正在更新中。 | | DELETING | 该主题正在删除中。 | ## 了解主题配置 该`configs`字段包含主题的 Kafka 配置属性，这些属性以 Base64 格式编码。要以可读格式查看配置，您需要解码 Base64 字符串。 以下示例显示了如何在 Linux 或 macOS 上使用`base64`命令对配置进行解码。 ``` echo "Y29tcHJlc3Npb24udHlwZT1wcm9kdWNlcgpyZXRlbnRpb24ubXM9NjA0ODAwMDAw" | base64 --decode ``` 解码后的输出以键值格式显示主题配置属性。 ``` compression.type=producer retention.ms=604800000 ``` 有关主题级配置属性的更多信息，请参阅。[主题级别的 Amazon MSK 配置](msk-configuration-properties.md#msk-topic-confinguration) # 使用 API 描述主题 要使用 API 描述主题，请参阅[DescribeTopic](https://docs.aws.amazon.com//msk/1.0/apireference/v1-clusters-clusterarn-topics-topicname.html#DescribeTopic)。 # 查看主题的分区信息 您可以检索有关 MSK Provisioned 集群中特定主题分区的详细信息。此信息包括分区号、领导代理、副本代理和同步副本 (ISR)。这对于监控分区分布、识别复制不足的分区或解决复制问题非常有用。 **注意** 此 API 响应反映了大约每分钟更新一次的数据。要了解更改后的最新主题状态，请在查询前等待大约一分钟。 **Topics** + [使用查看分区信息 AWS 管理控制台](describe-topic-partitions-console.md) + [使用查看分区信息 AWS CLI](describe-topic-partitions-cli.md) + [使用 API 查看分区信息](describe-topic-partitions-api.md) # 使用查看分区信息 AWS 管理控制台 1. 登录并在[https://console.aws.amazon.com/msk/家中打开 Amazon MSK 控制台？ AWS 管理控制台 region=us](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)-east-1\$1/home/。 1. 在集群列表中，选择包含该主题的集群的名称。 1. 在集群详细信息页面上，选择**主题**选项卡。 1. 在主题列表中，选择要查看其分区信息的主题的名称。 1. 在主题详细信息页面上，将显示分区信息，显示每个分区的分区号、领导代理、副本和同步副本。 # 使用查看分区信息 AWS CLI 运行以下命令，*ClusterArn*替换为集群的 Amazon 资源名称 (ARN) 和*TopicName*主题名称。 ``` aws kafka describe-topic-partitions --cluster-arn ClusterArn --topic-name TopicName ``` 该 命令的输出如以下 JSON 示例所示。 ``` { "partitions": [ { "partition": 0, "leader": 1, "replicas": [1, 2, 3], "isr": [1, 2, 3] }, { "partition": 1, "leader": 2, "replicas": [2, 3, 1], "isr": [2, 3, 1] }, { "partition": 2, "leader": 3, "replicas": [3, 1, 2], "isr": [3, 1] } ] } ``` ## 了解分区信息 响应包含每个分区的以下信息： + **分区**-分区号。分区从 0 开始编号。 + **le** ader — 此分区的领导者的代理 ID。领导者处理该分区的所有读取和写入请求。 + **replicas** — 包含此分 IDs 区副本的代理列表。这包括同步和 out-of-sync副本。 + **isr** — 同步副本 IDs 的代理列表。这些副本会完全赶上领导者，如果需要，可以接管领导者的职务。 在上面的示例中，分区 2 有一个 out-of-sync副本。该`replicas`列表包括经纪商 2，但`isr`列表中没有。这表明 broker 2 没有完全赶上该分区的领导者。 ## 对结果进行分页 如果您的主题有多个分区，则可以使用分页功能以较小的批量检索结果。使用`--max-results`参数指定要返回的最大分区数，并使用`--next-token`参数检索下一页的结果。 ``` aws kafka describe-topic-partitions --cluster-arn ClusterArn --topic-name TopicName --max-results 10 ``` 如果有更多结果可用，则响应中会包含一个`nextToken`值。使用此令牌检索下一页的结果。 ``` aws kafka describe-topic-partitions --cluster-arn ClusterArn --topic-name TopicName --max-results 10 --next-token NextToken ``` ## 常见使用案例 查看分区信息对以下几种情况很有用： + **识别复制不足的分区**-比较`replicas`和`isr`列表以确定某些副本不同步的分区。这可能表示性能问题或代理问题。 + **监控分区分布**-检查分区领导者在代理之间是否均匀分布，以确保负载平衡。 + 对@@ **复制问题进行故障排除**-通过查看 ISR 列表来确定哪些代理在跟上复制速度时遇到问题。 + **规划分区重新平衡**-在执行重新平衡操作之前，请使用此信息了解当前分区布局。 # 使用 API 查看分区信息 要使用 API 查看分区信息，请参阅[DescribeTopicPartitions](https://docs.aws.amazon.com//msk/1.0/apireference/v1-clusters-clusterarn-topics-topicname-partitions.html#DescribeTopicPartitions)。 # 在 Amazon MSK 集群中创建主题 您可以直接使用此 API 在您的 MSK 预配置集群中创建主题，而无需设置任何自定义 Kafka。 AdminClient创建主题时，您可以指定主题名称、分区数、重复因子以及可选的主题配置。 **Topics** + [使用创建主题 AWS 管理控制台](create-topic-console.md) + [使用创建主题 AWS CLI](create-topic-cli.md) + [使用 API 创建主题](create-topic-api.md) # 使用创建主题 AWS 管理控制台 1. 登录并在[https://console.aws.amazon.com/msk/家中打开 Amazon MSK 控制台？ AWS 管理控制台 region=us](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)-east-1\$1/home/。 1. 在集群列表中，选择要在其中创建主题的集群的名称。 1. 在集群详细信息页面上，选择**主题**选项卡。 1. 选择**创建主题**。 1. 输入主题名称、分区计数和重复因子。（可选）添加配置。您可以同时创建多个主题。 1. 选择**创建主题**。 # 使用创建主题 AWS CLI 运行以下命令，*ClusterArn*替换为集群的 Amazon 资源名称 (ARN)。如果您没有该集群的 ARN，可以通过列出所有集群来找到它。有关更多信息，请参阅 [列出 Amazon MSK 集群](msk-list-clusters.md)。 ``` aws kafka create-topic --cluster-arn ClusterArn --topic-name MyTopic --partition-count 3 --replication-factor 3 ``` 该 命令的输出如以下 JSON 示例所示。 ``` { "topicArn": "arn:aws:kafka:us-east-1:123456789012:topic/MyCluster/abcd1234-abcd-dcba-4321-a1b2abcd9f9f-2/MyTopic", "topicName": "MyTopic", "status": "CREATING" } ``` # 使用 API 创建主题 要使用 API 创建主题，请参阅[CreateTopic](https://docs.aws.amazon.com//msk/1.0/apireference/v1-clusters-clusterarn-topics.html#CreateTopic)。 # 更新 Amazon MSK 集群中的主题 更新现有主题的分区计数或主题级配置。此操作无需重新创建即可修改主题。 **注意** 您可以在单个 API 调用中更新分区计数或主题配置，但不能同时更新两者。要更新两者，请单独调用 API。 **Topics** + [使用更新主题 AWS 管理控制台](update-topic-console.md) + [使用更新主题 AWS CLI](update-topic-cli.md) + [使用 API 更新主题](update-topic-api.md) # 使用更新主题 AWS 管理控制台 1. 登录并在[https://console.aws.amazon.com/msk/家中打开 Amazon MSK 控制台？ AWS 管理控制台 region=us](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)-east-1\$1/home/。 1. 在集群列表中，选择包含要更新的主题的集群的名称。 1. 在集群详细信息页面上，选择**主题**选项卡。 1. 选择要更新的主题，然后从 “**操作**” 中选择 **“编辑分区设置****” 或 “编辑配置”**。 1. 根据需要更新分区计数或配置。 1. 选择**保存**。 # 使用更新主题 AWS CLI 运行以下命令，*ClusterArn*替换为集群的 Amazon 资源名称 (ARN) 和*TopicName*要更新的主题名称。 ``` aws kafka update-topic --cluster-arn ClusterArn --topic-name TopicName --partition-count 6 ``` 该 命令的输出如以下 JSON 示例所示。 ``` { "topicArn": "arn:aws:kafka:us-east-1:123456789012:topic/MyCluster/abcd1234-abcd-dcba-4321-a1b2abcd9f9f-2/MyTopic", "topicName": "MyTopic", "status": "UPDATING" } ``` # 使用 API 更新主题 要使用 API 更新主题，请参阅[UpdateTopic](https://docs.aws.amazon.com//msk/1.0/apireference/v1-clusters-clusterarn-topics-topicname.html#UpdateTopic)。 # 删除 Amazon MSK 集群中的主题 删除主题会永久删除其所有数据、元数据和分区信息。此操作无法撤消。 **Topics** + [使用删除主题 AWS 管理控制台](delete-topic-console.md) + [使用删除主题 AWS CLI](delete-topic-cli.md) + [使用 API 删除主题](delete-topic-api.md) # 使用删除主题 AWS 管理控制台 1. 登录并在[https://console.aws.amazon.com/msk/家中打开 Amazon MSK 控制台？ AWS 管理控制台 region=us](https://console.aws.amazon.com/msk/home?region=us-east-1#/home/)-east-1\$1/home/。 1. 在集群列表中，选择包含要删除的主题的集群的名称。 1. 在集群详细信息页面上，选择**主题**选项卡。 1. 选择要删除的主题，然后从 “**操作**” 中选择 “**删除**”。 1. 确认删除，然后选择**删除**。 # 使用删除主题 AWS CLI 运行以下命令，*ClusterArn*替换为集群的 Amazon 资源名称 (ARN) 和*TopicName*要删除的主题的名称。 ``` aws kafka delete-topic --cluster-arn ClusterArn --topic-name TopicName ``` 该 命令的输出如以下 JSON 示例所示。 ``` { "topicArn": "arn:aws:kafka:us-east-1:123456789012:topic/MyCluster/abcd1234-abcd-dcba-4321-a1b2abcd9f9f-2/MyTopic", "topicName": "MyTopic", "status": "DELETING" } ``` # 使用 API 删除主题 要使用 API 删除主题，请参阅[DeleteTopic](https://docs.aws.amazon.com//msk/1.0/apireference/v1-clusters-clusterarn-topics-topicname.html#DeleteTopic)。