华为云用户手册

支持的授权项 策略包含系统策略和自定义策略，如果系统策略不满足授权要求，管理员可以创建自定义策略，并通过给用户组授予自定义策略来进行精细的访问控制。策略支持的操作与API相对应，授权项列表说明如下： 权限：允许或拒绝某项操作。 对应API接口：自定义策略实际调用的API接口。 授权项：自定义策略中支持的Action，在自定义策略中的Action中写入授权项，可以实现授权项对应的权限功能。 IAM 项目（Project）/企业项目（Enterprise Project）：自定义策略的授权范围，包括IAM项目与企业项目。授权范围如果同时支持IAM项目和企业项目，表示此授权项对应的自定义策略，可以在IAM和企业管理两个服务中给用户组授权并生效。如果仅支持IAM项目，不支持企业项目，表示仅能在IAM中给用户组授权并生效，如果在企业管理中授权，则该自定义策略不生效。管理员可以在授权项列表中查看授权项是否支持IAM项目或企业项目，“√”表示支持，“×”表示暂不支持。关于IAM项目与企业项目的区别，详情请参见：IAM与企业管理的区别。 DMS for Kafka的支持自定义策略授权项如下所示： 生命周期管理，包含Kafka实例所有生命周期接口对应的授权项，如创建实例、查询实例列表、修改实例信息、批量重启或删除实例等接口。 实例管理，包括Kafka实例管理接口对应的授权项，如重置密码、开启或关闭实例自动创建Topic功能等接口。 转储管理，包括转储管理接口对应的授权项，如创建实例的转储节点、创建转储任务、查询转储任务列表等接口。 规格变更管理，包括实例规格变更管理接口对应的授权项，如实例规格变更接口。 主题管理，包括Topic管理接口对应的授权项，如创建Topic、查询Topic、修改Topic等接口。 用户管理，包括用户管理接口对应的授权项，如创建用户、查询用户列表、设置用户权限等接口。 消息查询，包括消息查询接口对应的授权项，如查询消息接口。 后台任务管理，包括实例的后台任务管理接口对应的授权项，如查询实例的后台任务列表、查询后台任务管理中的指定记录等接口。 标签管理，包括实例的标签管理接口对应的授权项，如查询实例标签、查询项目标签等接口。 其他：包括开启关闭公网访问接口。

基本概念 账号 用户注册账号时，账号对其所拥有的资源及云服务具有完全的访问权限，可以重置用户密码、分配用户权限等。由于账号是付费主体，为了确保账号安全，建议您不要直接使用账号进行日常管理工作，而是创建用户并使用他们进行日常管理工作。 用户 由账号在IAM中创建的用户，是云服务的使用人员，具有身份凭证（密码和访问密钥）。 在我的凭证下，您可以查看帐号ID和用户ID。通常在调用API的鉴权过程中，您需要用到账号、用户和密码等信息。 区域（Region） 从地理位置和网络时延维度划分，同一个Region内共享弹性计算、块存储、对象存储、VPC网络、弹性公网IP、镜像等公共服务。Region分为通用Region和专属Region，通用Region指面向公共租户提供通用云服务的Region；专属Region指只承载同一类业务或只面向特定租户提供业务服务的专用Region。 可用区（AZ，Availability Zone） 一个可用区是一个或多个物理数据中心的集合，有独立的风火水电，AZ内逻辑上再将计算、网络、存储等资源划分成多个集群。一个Region中的多个AZ间通过高速光纤相连，以满足用户跨AZ构建高可用性系统的需求。 项目 区域默认对应一个项目，这个项目由系统预置，用来隔离物理区域间的资源（计算资源、存储资源和网络资源），以默认项目为单位进行授权，用户可以访问您账号中该区域的所有资源。如果您希望进行更加精细的权限控制，可以在区域默认的项目中创建子项目，并在子项目中创建资源，然后以子项目为单位进行授权，使得用户仅能访问特定子项目中资源，使得资源的权限控制更加精确。 图1 项目隔离模型 同样在我的凭证下，您可以查看项目ID。 企业项目 企业项目是项目的升级版，针对企业不同项目间资源的分组和管理，是逻辑隔离。企业项目中可以包含多个区域的资源，且项目中的资源可以迁入迁出。 关于企业项目ID的获取及企业项目特性的详细信息，请参见《企业管理服务用户指南》。 父主题： 使用前必读

请求参数 表2 请求Body参数 参数 是否必选 参数类型 描述 specification 否 String 部署Smart Connect的规格，基准带宽，表示单位时间内传送的最大数据量。请保持和当前实例规格一致。仅老规格实例需要填写。 取值范围： 100MB 300MB 600MB 1200MB node_cnt 否 String Smart Connect节点数量。不能小于2个。 如果不填，默认是2个。 spec_code 否 String 转储节点规格编码。仅老规格实例需要填写。

请求示例 创建实例的Smart Connect节点，规格为100MB，节点数量为2。 POST https://{endpoint}/v2/{project_id}/instances/{instance_id}/connector { "specification" : "100MB", "node_cnt" : 2, "spec_code" : "kafka.c3.mini.connector" }

请求示例 创建实例标签，标签名为key1、key2，值为value1、value2。 POST https://{endpoint}/v2/{project_id}/kafka/{instance_id}/tags/action { "action" : "create", "tags" : [ { "key" : "key1", "value" : "value1" }, { "key" : "key2", "value" : "value2" } ] }

请求参数 表2 请求Body参数 参数 是否必选 参数类型 描述 action 否 String 操作标识（仅支持小写）: create（创建） delete（删除） tags 否 Array of TagEntity objects 标签列表。 表3 TagEntity 参数 是否必选 参数类型 描述 key 否 String 标签键。 不能为空。 对于同一个实例，Key值唯一。 长度为1~128个字符（中文也可以输入128个字符）。 由任意语种字母、数字、空格和字符组成，字符仅支持_ . : = + - @ 首尾字符不能为空格。 value 否 String 标签值。 长度为0~255个字符（中文也可以输入255个字符）。 由任意语种字母、数字、空格和字符组成，字符仅支持_ . : = + - @ 首尾字符不能为空格。

请求参数 表2 请求Body参数 参数 是否必选 参数类型 描述 partitions 否 Array of partitions objects 期望调整的分区副本分配情况。 表3 partitions 参数 是否必选 参数类型 描述 partition 否 Integer 分区ID。 replicas 否 Array of integers 副本期望所在的broker ID。其中Array首位为leader副本，所有分区需要有同样数量的副本，副本数不能大于总broker的数量。

请求示例 修改Topic分区的副本分布位置，分区1的副本分布在broker 1和broker 2，Leader副本在broker 1。 POST https://{endpoint}/v2/{project_id}/instances/{instance_id}/management/topics/{topic}/replicas-reassignment { "partitions" : [ { "partition" : 1, "replicas" : [ 1, 2 ] }, { "partition" : 0, "replicas" : [ 0, 1 ] } ] }

URI POST /v2/{project_id}/instances/{instance_id}/management/topics/{topic}/replicas-reassignment 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 项目ID，获取方式请参见获取项目ID。 instance_id 是 String 实例ID。 topic 是 String Topic名称。

URI GET /v1.0/{project_id}/instances?engine={engine}&name={name}&status={status}&id={id}&includeFailure={includeFailure}&exactMatchName={exactMatchName}&enterprise_project_id={enterprise_project_id} 参数说明见表1。 表1 参数说明 参数 类型 必选 说明 project_id String 是 项目ID。 engine String 否 消息引擎：kafka。 name String 否 实例名称。 id String 否 实例ID。 status String 否 实例状态。详细状态说明见实例状态说明。 includeFailure String 否 是否返回创建失败的实例数。 当参数值为“true”时，返回创建失败的实例数。参数值为“false”或者其他值，不返回创建失败的实例数。 exactMatchName String 否 是否按照实例名称进行精确匹配查询。 默认为“false”，表示模糊匹配实例名称查询。若参数值为“true”表示按照实例名称进行精确匹配查询。 enterprise_project_id String 否 企业项目ID。

URI GET /v1.0/{project_id}/instances/{instance_id}/manage/topics/{topic}/partitions/{partition}/beginning-message 参数说明如下表所示。 表1 参数说明 参数 类型 必选 说明 project_id String 是 项目ID。 instance_id String 是 实例ID。 topic String 是 Topic名称。 partition Integer 是 分区编号。

响应消息 响应参数 参数说明见表2。 表2 响应参数说明 参数 类型 说明 topic String topic名称。 partition Integer 分区编号。 message_offset Long 最早消息位置。 timestamp Long 最早消息时间戳。 响应示例 { "topic": "mytest", "partition": 0, "message_offset ": 9, "timestamp": 1568125039164 }

请求参数 表2 请求Body参数 参数 是否必选 参数类型 描述 user 否 String 用户名 client 否 String 客户端ID user-default 否 Boolean 是否使用用户默认设置（是则表示对全部用户限流）。 client-default 否 Boolean 是否使用客户端默认设置（是则表示对全部客户端限流）。 producer-byte-rate 否 Long 生产上限速率（单位为B/s） consumer-byte-rate 否 Long 消费上限速率（单位为B/s）

请求示例 修改用户/客户端流控配置。 PUT https://{endpoint}/v2/kafka/{project_id}/instances/{instance_id}/kafka-user-client-quota { "user" : "", "client" : "", "user-default" : false, "client-default" : true, "producer-byte-rate" : 3145728, "consumer-byte-rate" : 2097152 }

响应示例 状态码： 200 查询Kafka集群元数据信息成功。 { "cluster" : { "controller" : "2", "brokers" : [ { "host" : "192.168.0.159", "port" : 9093, "broker_id" : "0", "is_controller" : false, "version" : "1.1.0", "register_time" : 1588754647872, "is_health" : true }, { "host" : "192.168.0.48", "port" : 9093, "broker_id" : "1", "is_controller" : false, "version" : "1.1.0", "register_time" : 1588754647653, "is_health" : true }, { "host" : "192.168.0.212", "port" : 9093, "broker_id" : "2", "is_controller" : true, "version" : "1.1.0", "register_time" : 1588754647284, "is_health" : true } ], "topics_count" : 3, "partitions_count" : 9, "online_partitions_count" : 9, "replicas_count" : 27, "isr_replicas_count" : 27, "consumers_count" : 0 } }

响应参数 状态码： 200 表2 响应Body参数 参数 参数类型 描述 cluster cluster object 集群基本信息。 表3 cluster 参数 参数类型 描述 controller String 控制器ID。 brokers Array of brokers objects 节点列表。 topics_count Integer 主题数量。 partitions_count Integer 分区数量。 online_partitions_count Integer 在线分区数量。 replicas_count Integer 副本数量。 isr_replicas_count Integer ISR（In-Sync Replicas） 副本总数。 consumers_count Integer 消费组数量。 表4 brokers 参数 参数类型 描述 host String 节点IP。 port Integer 端口号。 broker_id String 节点ID。 is_controller Boolean 是否为contoller节点。 version String 服务端版本。 register_time Long broker注册时间，为unix时间戳格式。 is_health Boolean Kafka实例节点的连通性是否正常。

修订记录 发布日期 修订记录 2023-11-10 本次变更如下： 新增获取实例配置和修改实例配置接口。 2023-07-26 本次变更如下： 新增查询Topic的分区列表和查询Topic的当前生产者列表接口。 2023-06-06 本次变更如下： 新增创建消费组接口。 2023-04-23 本次变更如下： 新增Kafka实例批量删除Group接口。 2023-02-03 本次变更如下： 更新创建实例、实例规格变更和查询实例的扩容规格列表的URI，支持实例新规格。 2022-06-30 本次变更如下： 在创建实例的“specification”参数中，增加新规格描述。 在创建实例中，新增“broker_num”参数。 2022-01-26 本次变更如下： 查询产品规格列表V2接口变更为新版本，旧版本接口移入历史API中。 2021-12-14 本次变更如下： 在权限和授权项中，将授权项明细接口从V1改为V2。 2021-09-13 本次变更如下： 在修改Kafka实例Topic中，增加Topic名称不能修改的描述。 2021-08-16 本次变更如下： 修改Kafka实例创建Topic和新增Kafka实例指定Topic分区的分区数最大值。 2021-05-11 本次变更如下： 修改开启或关闭实例自动创建topic功能的返回状态码和返回描述。 2021-04-16 新增以下接口： 查询用户列表 创建用户 批量删除用户 重置用户密码 查询用户权限 设置用户权限 2020-08-25 新增以下接口： 创建实例的转储节点 创建转储任务 查询转储任务列表 修改转储任务的配额 查询单个转储任务 删除单个转储任务 查询实例的扩容规格列表 实例规格变更 2020-08-18 新增以下接口： 重置密码 重置Manager密码 开启或关闭实例自动创建topic功能 修改实例跨VPC访问的内网IP 修改Kafka实例Topic 查询实例的后台任务列表 查询后台任务管理中的指定记录 删除后台任务管理中的指定记录 批量添加或删除实例标签 查询实例标签 查询项目标签 2020-08-06 本次变更如下： 将API V1移动至历史API。 2020-07-07 本次变更如下： 新增API V2（推荐）章节的V2接口。 2019-12-10 新增以下接口： 查询分区指定偏移量的消息 查询分区指定时间段的消息 查询分区最新消息的位置 查询分区最早消息的位置 查询Kafka集群元数据信息 查询消费组信息 重置消费组消费进度到指定位置 查询实例在 CES 的监控层级关系 查询Kafka实例所有消费组对应的协调器信息 新增Kafka实例指定Topic分区 调整Kafka实例Topic分区的副本 2019-06-04 第一次正式发布。

响应消息 响应参数 参数说明见表2。 表2 参数说明 参数 类型 说明 coordinators Array 所有消费组对应的协调器列表。参数参见表3。 表3 coordinators参数说明 参数 类型 说明 group_id String 消费组ID。 id Integer 对应协调器的broker id。 host String 对应协调器的地址。 port Integer 端口号。 响应示例 { "coordinators": [ { "group_id": "XXXX", "id": 2, "host": "172.31.1.15", "port": 9091 }, { "group_id": "XXXX", "id": 2, "host": "172.31.1.15", "port": 9092 }, { "group_id": "XXXX", "id": 2, "host": "172.31.1.15", "port": 9092 } ] }

响应示例 状态码： 200 查询Kafka实例的协调器信息成功。 { "coordinators" : [ { "group_id" : "XXXX", "id" : 2, "host" : "172.31.1.15", "port" : 9091 }, { "group_id" : "XXXX", "id" : 2, "host" : "172.31.1.15", "port" : 9092 }, { "group_id" : "XXXX", "id" : 2, "host" : "172.31.1.15", "port" : 9092 } ] }

响应参数 状态码： 200 表2 响应Body参数 参数 参数类型 描述 coordinators Array of coordinators objects 所有消费组对应的协调器列表。 表3 coordinators 参数 参数类型 描述 group_id String 消费组ID。 id Integer 对应协调器的broker id。 host String 对应协调器的地址。 port Integer 端口号。

请求示例 重置的消费进度到指定偏移量。 POST https://{endpoint}/v2/{project_id}/instances/{instance_id}/management/groups/{group}/reset-message-offset { "topic" : "test", "partition" : 0, "message_offset" : 10 } 重置的消费进度到指定时间。 POST https://{endpoint}/v2/{project_id}/instances/{instance_id}/management/groups/{group}/reset-message-offset { "topic" : "test", "partition" : 0, "timestamp" : 1571812144000 }

URI POST /v2/{project_id}/instances/{instance_id}/management/groups/{group}/reset-message-offset 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 项目ID，获取方式请参见获取项目ID。 instance_id 是 String 实例ID。 group 是 String 消费组名称。

请求参数 表2 请求Body参数 参数 是否必选 参数类型 描述 topic 否 String topic名称。 partition 是 Integer 分区编号，默认值为-1，若传入值为-1，则重置所有分区。 message_offset 否 Long 重置消费进度到指定偏移量。 如果传入offset小于当前最小的offset，则重置到最小的offset。 如果大于最大的offset，则重置到最大的offset。 message_offset、timestamp二者必选其一。 timestamp 否 Long 重置消费进度到指定时间，格式为unix时间戳，单位为毫秒。 如果传入timestamp早于当前最早的timestamp，则重置到最早的timestamp。 如果晚于最晚的timestamp，则重置到最晚的timestamp。 message_offset、timestamp二者必选其一。

请求参数 表2 请求Body参数 参数 是否必选 参数类型 描述 reassignments 是 Array of PartitionReassignEntity objects 重平衡分配方案。 throttle 否 Integer 重平衡门限值。 is_schedule 否 Boolean 是否作为定时任务执行。若非定时执行，则is_schedule 和execute_at字段可为空；若为定时执行，is_schedule为true，execute_at字段非空。 execute_at 否 Long 定时时间，格式为Unix时间戳，单位为毫秒 表3 PartitionReassignEntity 参数 是否必选 参数类型 描述 topic 是 String topic名称 brokers 否 Array of integers 分区重平衡到的broker列表，自动生成分配方案时需指定该参数。 replication_factor 否 Integer 副本因子，自动生成分配方案时可指定。 assignment 否 Array of TopicAssignment objects 手动指定的分配方案。brokers参数与该参数不能同时为空。 表4 TopicAssignment 参数 是否必选 参数类型 描述 partition 否 Integer 手动指定分配方案时的分区号。 partition_brokers 否 Array of integers 手动指定某个分区将要分配的broker列表

请求示例 POST https://{endpoint}/v2/kafka/{project_id}/instances/{instance_id}/reassign { "reassignments" : [ { "topic" : "topic-1513476102", "brokers" : [ 0, 1, 2 ], "replication_factor" : 3, "assignment" : [ { "partition" : 0, "partition_brokers" : [ 0, 1, 2 ] }, { "partition" : 1, "partition_brokers" : [ 1, 2, 0 ] }, { "partition" : 2, "partition_brokers" : [ 2, 0, 1 ] } ] }, { "topic" : "topic-1513558717", "brokers" : [ 0, 1, 4 ], "replication_factor" : 3, "assignment" : [ { "partition" : 0, "partition_brokers" : [ 0, 1, 2 ] }, { "partition" : 1, "partition_brokers" : [ 1, 2, 0 ] }, { "partition" : 2, "partition_brokers" : [ 2, 0, 1 ] } ] } ], "throttle" : 10000000 }

实例状态说明 表1 实例状态说明 状态 说明 Creating 申请实例后，在实例状态进入运行中之前的状态。 Running 实例正常运行状态。在这个状态的实例可以运行您的业务。 Faulty 实例处于故障的状态。 Restarting 实例正在进行重启操作。 Starting 实例从已冻结到运行中的中间状态。 Changing 实例正在进行规格变更操作。 Change failed 实例处于规格变更操作失败的状态。 Frozen 实例处于已冻结状态，用户可以在“我的订单”中续费开启冻结的实例。 Freezing 实例从运行中到已冻结的中间状态。 Upgrading 实例正在进行升级操作。 Rolling back 实例正在进行回滚操作。 父主题： 附录

响应消息 响应参数 参数说明见表2。 表2 响应参数说明 参数 类型 说明 group_id String 消费组名称。 state String 消费组状态。包含以下状态： Dead：消费组内没有任何成员，且没有任何元数据。 Empty：消费组内没有任何成员，存在元数据。 PreparingRebalance：准备开启rebalance。 CompletingRebalance：所有成员加入group。 Stable：消费组内成员可正常消费。 coordinator_id Integer 协调器编号 members Array of object members 消费者列表。参数参见表3。 group_message_offsets Array of group_offsets 消费进度。参数参见表4。 assignment_strategy String 分区分配策略。 表3 members参数说明 参数 类型 说明 host String 消费组consumer地址。 assignment Array of object assignment consumer分配到的分区信息。参数请参见表5。 member_id String 消费组consumer的ID。 client_id String 客户端ID。 表4 group_message_offsets参数说明 参数 类型 说明 topic String topic名称。 partition Integer 分区编号。 message_current_offset Long 当前消费进度。 message_log_end_offset Long 最大消息位置（LEO）。 lag Long 剩余可消费消息数，即消息堆积数。 表5 assignment参数说明 参数 类型 说明 topic String topic名称。 partitions Array of integer 分区列表。 响应示例 { "group": { "members": [ { "host": "/172.31.1.102", "assignment": [ { "topic": "test", "partitions": [ 0, 1, 2 ] } ], "member_id": "consumer-1-6b8ee551-d499-47d4-9beb-ba1527496785", "client_id": "consumer-1" } ], "state": "STABLE", "group_id": "test-consumer-group", "coordinator_id": 2, "group_message_offsets": [ { "partition": 0, "lag": 31396, "topic": "test", "message_current_offset": 935, "message_log_end_offset": 32331 }, { "partition": 0, "lag": 0, "topic": "aaaa", "message_current_offset": 0, "message_log_end_offset ": 0 }, { "partition": 1, "lag": 31279, "topic": "test", "message_current_offset": 1058, "message_log_end_offset ": 32337 }, { "partition": 1, "lag": 0, "topic": "aaaa", "message_current_offset": 0, "message_log_end_offset": 0 }, { "partition": 2, "lag": 31603, "topic": "test", "message_current_offset": 739, "message_log_end_offset": 32342 } ], "assignment_strategy": "range" } }

响应示例 状态码： 200 查询实例集群的消费组信息成功。 { "group" : { "members" : [ { "host" : "/172.31.1.102", "assignment" : [ { "topic" : "test", "partitions" : [ 0, 1, 2 ] } ], "member_id" : "consumer-1-6b8ee551-d499-47d4-9beb-ba1527496785", "client_id" : "consumer-1" } ], "state" : "STABLE", "group_id" : "test-consumer-group", "coordinator_id" : 2, "group_message_offsets" : [ { "partition" : 0, "lag" : 31396, "topic" : "test", "message_current_offset" : 935, "message_log_end_offset" : 32331 }, { "partition" : 0, "lag" : 0, "topic" : "aaaa", "message_current_offset" : 0, "message_log_end_offset" : 0 }, { "partition" : 1, "lag" : 31279, "topic" : "test", "message_current_offset" : 1058, "message_log_end_offset" : 32337 }, { "partition" : 1, "lag" : 0, "topic" : "aaaa", "message_current_offset" : 0, "message_log_end_offset" : 0 }, { "partition" : 2, "lag" : 31603, "topic" : "test", "message_current_offset" : 739, "message_log_end_offset" : 32342 } ], "assignment_strategy" : "range" } }

响应参数 状态码： 200 表2 响应Body参数 参数 参数类型 描述 group group object 消费组信息。 表3 group 参数 参数类型 描述 group_id String 消费组名称。 state String 消费组状态。包含以下状态： Dead：消费组内没有任何成员，且没有任何元数据。 Empty：消费组内没有任何成员，存在元数据。 PreparingRebalance：准备开启rebalance。 CompletingRebalance：所有成员加入group。 Stable：消费组内成员可正常消费。 coordinator_id Integer 协调器编号。 members Array of members objects 消费者列表。 group_message_offsets Array of group_message_offsets objects 消费进度。 assignment_strategy String 分区分配策略。 表4 members 参数 参数类型 描述 host String 消费组consumer地址。 assignment Array of assignment objects consumer分配到的分区信息。 member_id String 消费组consumer的ID。 client_id String 客户端ID。 表5 assignment 参数 参数类型 描述 topic String topic名称。 partitions Array of integers 分区列表。 表6 group_message_offsets 参数 参数类型 描述 partition Integer 分区编号。 lag Long 剩余可消费消息数，即消息堆积数。 topic String topic名称。 message_current_offset Long 当前消费进度。 message_log_end_offset Long 最大消息位置（LEO）。

请求消息 请求参数 表2 参数说明 参数 类型 必选 说明 topic String 是 topic名称。 partition Integer 否 分区编号，默认值为-1，若传入值为-1，则重置所有分区。 message_offset Long 二者必选其一 重置的消费进度到指定偏移量，如果传入offset小于当前最小的offset，则重置到最小的offset，如果大于最大的offset，则重置到最大的offset。 timestamp Long 重置的消费进度到指定时间，格式为unix时间戳。如果传入timestamp早于当前最早的timestamp，则重置到最早的timestamp，如果晚于最晚的timestamp，则重置到最晚的timestamp。 请求示例1 { "topic": "test", "partition": 0, "message_offset": 10 } 请求示例2 { "topic": "test", "partition": 0, "timestamp": 1571812144 }