华为云用户手册

URI GET /v1.0/{project_id}/instances/{instance_id}/manage/topics/{topic}/messages?partition={partition}&start_time={start_time}&end_time={end_time}&limit={limit}&offset={offset} 参数说明请参考表1 表1 参数说明 参数 类型 必选 说明 project_id String 是 项目ID。 instance_id String 是 实例ID。 topic String 是 Topic名称。 partition Integer 否 分区编号，默认值为-1，若传入值为-1，则查询所有分区。 start_time Long 否 查询起始时间，为unix时间戳格式，默认值为0。 end_time Long 否 查询结束时间，为unix时间戳格式，默认值为系统当前时间。 limit Integer 否 单页返回消息数，默认值为10。 offset Integer 否 查询的页码，默认值为1。

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 messages Array of messages objects 消息列表。 messages_count Integer 消息总数。 offsets_count Integer 总页数。 offset Integer 当前页数。 表4 messages 参数 参数类型 描述 topic String topic名称。 partition Integer 分区编号。 message_offset Long 消息编号。 size Integer 消息大小，单位字节。 timestamp Long 生产消息的时间。 格式为Unix时间戳。单位为毫秒。

响应示例 状态码： 200 查询分区指定时间段的消息成功。 { "messages" : [ { "topic" : "mytest", "partition" : 0, "message_offset" : 7, "size" : 6, "timestamp" : 1568125036045 } ], "messages_count" : 1, "offsets_count" : 1, "offset" : 1 }

URI GET /v2/{project_id}/instances/{instance_id}/management/topics/{topic}/messages 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 项目ID，获取方式请参见获取项目ID。 instance_id 是 String 实例ID。 topic 是 String Topic名称。 Topic名称必现以字母开头且只支持大小写字母、中横线、下划线以及数字。 表2 Query参数 参数 是否必选 参数类型 描述 start_time 否 String 查询起始时间，为unix时间戳格式，默认值为0。 end_time 否 String 查询结束时间，为unix时间戳格式，默认值为系统当前时间。 limit 否 Integer 单页返回消息数，默认值为10。 offset 否 Integer 偏移量，表示从此偏移量开始查询， offset大于等于0。 partition 否 String 分区编号，默认值为-1，若传入值为-1，则查询所有分区。

响应参数 状态码： 200 表2 响应Body参数 参数 参数类型 描述 tags Array of TagEntity objects 标签列表 表3 TagEntity 参数 参数类型 描述 key String 标签键。 不能为空。 对于同一个实例，Key值唯一。 长度为1~128个字符（中文也可以输入128个字符）。 由任意语种字母、数字、空格和字符组成，字符仅支持_ . : = + - @ 首尾字符不能为空格。 value String 标签值。 长度为0~255个字符（中文也可以输入255个字符）。 由任意语种字母、数字、空格和字符组成，字符仅支持_ . : = + - @ 首尾字符不能为空格。

响应示例 状态码： 200 查询实例的后台任务列表 { "task_count" : "4", "tasks" : [ { "id" : "8abfa7b372160bfd0172165864064079", "name" : "modifyAutoTopic", "user_name" : "paas_dms", "user_id" : "3df5acbc24a54fadb62a043c9000a307", "params" : "{\"old_auto_status\":true,\"new_auto_status\":false}", "status" : "EXECUTING", "created_at" : "2020-05-15T03:19:51.046Z", "updated_at" : "2020-05-15T03:19:51.065Z" }, { "id" : "8abfa7b372160bfd017216560af83e6e", "name" : "changeRetentionPolicy", "user_name" : "paas_dms", "user_id" : "3df5acbc24a54fadb62a043c9000a307", "params" : "{\"new_retention_policy\":\"produce_reject\",\"origin_retention_policy\":\"time_base\"}", "status" : "SUCCESS", "created_at" : "2020-05-15T03:17:17.176Z", "updated_at" : "2020-05-15T03:17:22.162Z" } ] }

URI GET /v2/{project_id}/instances/{instance_id}/tasks 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 项目ID，获取方式请参见获取项目ID。 instance_id 是 String 实例ID。 表2 Query参数 参数 是否必选 参数类型 描述 start 否 Integer 开启查询的任务编号。 limit 否 Integer 查询的任务个数。 begin_time 否 String 查询任务的最小时间，格式为YYYYMMDDHHmmss。 end_time 否 String 查询任务的最大时间，格式为YYYYMMDDHHmmss。

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 task_count String 任务数量。 tasks Array of tasks objects 任务列表。 表4 tasks 参数 参数类型 描述 id String 任务ID。 name String 任务名称。 user_name String 用户名。 user_id String 用户ID。 params String 任务参数。 status String 任务状态。 created_at String 启动时间。 updated_at String 结束时间。

URI GET /v2/{project_id}/instances/{instance_id}/management/topics/{topic}/partitions/{partition}/beginning-message 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 项目ID，获取方式请参见获取项目ID。 instance_id 是 String 实例ID。 topic 是 String Topic名称。 Topic名称必现以字母开头且只支持大小写字母、中横线、下划线以及数字。 partition 是 Integer 分区编号。

响应消息 响应参数 当参数action为delete，allFailure值为kafka时，响应返回为空表示删除成功。参数说明见表3。 表3 参数说明 参数 类型 说明 results Array 修改实例的结果。 表4 results参数说明 参数 类型 说明 instance String 实例ID。 result String 操作结果：success、failed。 响应示例 { "results": [ { "result": "success", "instance": "afc90a2a-a02c-4cba-94d5-58dfa9ad1e0d" }, { "result": "success", "instance": "67fc5f8d-3986-4f02-bb75-4075a23112de" } ] }

请求消息 请求参数 参数说明见表2。 表2 参数说明 参数 类型 必选 说明 action String 是 对实例的操作：restart、delete instances Array 否 实例的ID列表。 allFailure String 否 参数值为kafka，表示删除租户所有创建失败的Kafka实例。 请求示例 批量重启实例 POST https://{dms_endpoint}/v1.0/{project_id}/instances/action { "action" : "restart", "instances" : ["54602a9d-5e22-4239-9123-77e350df4a34", "7166cdea-dbad-4d79-9610-7163e6f8b640"] } 批量删除实例 POST https://{dms_endpoint}/v1.0/{project_id}/instances/action { "action" : "delete", "instances" : ["54602a9d-5e22-4239-9123-77e350df4a34", "7166cdea-dbad-4d79-9610-7163e6f8b640"] } 删除所有创建失败的实例 POST https://{dms_endpoint}/v1.0/{project_id}/instances/action { "action" : "delete", "allFailure" : "kafka" }

响应示例 状态码： 200 查询成功。 { "task_count" : "1", "tasks" : [ { "id" : "8abfa7b272adc5b40172b73130065ae7", "name" : "bindInstancePublicIp", "user_name" : "paas_dms", "user_id" : "3df5acbc24a54fadb62a043c9000a307", "params" : "{\"public_ip_id\":\"1aea7aed-e7d8-40ea-b3de-6f3ee9d5db9f\",\"public_ip_address\":\"100.93.2.18\",\"enable_public_ip\":true}", "status" : "SUCCESS", "created_at" : "2020-06-15T08:55:53.606Z", "updated_at" : "2020-06-15T08:55:56.600Z" } ] }

响应参数 状态码： 200 表2 响应Body参数 参数 参数类型 描述 task_count String 任务数量。 tasks Array of tasks objects 任务列表。 表3 tasks 参数 参数类型 描述 id String 任务ID。 name String 任务名称。 user_name String 用户名。 user_id String 用户ID。 params String 任务参数。 status String 任务状态。 created_at String 启动时间。 updated_at String 结束时间。

URI POST /v1.0/{project_id}/instances/{instance_id}/manage/topics/{topic}/partitions-reassignment 参数说明如下表所示。 表1 参数说明 参数 类型 必选 说明 project_id String 是 项目ID。 instance_id String 是 实例ID。 topic String 是 Topic名称。

API概览 表1 实例管理类接口 API 说明 生命周期管理 包括创建实例、修改实例信息、查询实例、删除实例、重启实例。 实例管理 包括重置密码、重置Manager密码、重启Manager、开启或关闭实例自动创建Topic功能、修改实例跨VPC访问的内网IP、查询Kafka集群元数据信息、查询消费组信息、重置消费组消费进度到指定位置、查询Kafka实例的协调器信息、修改分区的副本、查询Topic的磁盘存储情况、查询所有消费组、查询指定消费组信息、删除消费组、Kafka实例开始分区重平衡任务。 转储管理 包括创建实例的转储节点、创建转储任务、查询转储任务列表、修改转储任务的配额、查询单个转储任务、删除单个转储任务。 规格变更管理 包括查询实例的扩容规格列表、实例扩容。 主题管理 包括查询Topic、创建Topic、修改Topic、批量删除Topic、查询Topic的分区列表、查询Topic的当前生产者列表、查询Topic详细信息。 用户管理 包括查询用户列表、创建用户、删除用户、重置用户密码、查询用户权限、设置用户权限。 消息查询 包括查询消息、查询分区指定偏移量的消息、查询分区指定时间段的消息、查询分区最早/最新的消息位置。 后台任务管理 包括查询实例的后台任务列表、查询后台任务管理中的指定记录、删除后台任务管理中的指定记录。 标签管理 包括批量添加或删除实例标签、查询实例标签、查询项目标签。 其他接口 包括查询产品规格列表、查询可用区信息、查询维护时间窗、查询实例在CES的监控层级关系。

响应示例 状态码： 200 查询成功。 { "broker_list" : [ { "broker_name" : "broker-0", "data_disk_size" : "66G", "data_disk_use" : "53M", "data_disk_free" : "63G", "data_disk_use_percentage" : "1", "status" : "Success get info", "topic_list" : [ { "size" : "12K", "topic_name" : "topic-test", "topic_partition" : "2", "percentage" : 1.7339533025568183E-5 }, { "size" : "12K", "topic_name" : "__consumer_offsets", "topic_partition" : "4", "percentage" : 1.7339533025568183E-5 }, { "size" : "12K", "topic_name" : "__consumer_offsets", "topic_partition" : "3", "percentage" : 1.7339533025568183E-5 }, { "size" : "8.0K", "topic_name" : "__trace", "topic_partition" : "6", "percentage" : 1.1559688683712121E-5 }, { "size" : "8.0K", "topic_name" : "__trace", "topic_partition" : "4", "percentage" : 1.1559688683712121E-5 }, { "size" : "8.0K", "topic_name" : "__trace", "topic_partition" : "2", "percentage" : 1.1559688683712121E-5 }, { "size" : "8.0K", "topic_name" : "__trace", "topic_partition" : "0", "percentage" : 1.1559688683712121E-5 }, { "size" : "8.0K", "topic_name" : "topic-test", "topic_partition" : "0", "percentage" : 1.1559688683712121E-5 }, { "size" : "8.0K", "topic_name" : "topic-1568537362", "topic_partition" : "2", "percentage" : 1.1559688683712121E-5 }, { "size" : "8.0K", "topic_name" : "__consumer_offsets", "topic_partition" : "7", "percentage" : 1.1559688683712121E-5 } ] } ] }

URI GET /v2/{project_id}/instances/{instance_id}/topics/diskusage 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 项目ID，获取方式请参见获取项目ID。 instance_id 是 String 实例ID。 表2 Query参数 参数 是否必选 参数类型 描述 minSize 否 String 占用磁盘大小，默认值1G (1K，1M，1G)。 top 否 String 占用磁盘大小，查询top N。 percentage 否 String 占用磁盘大小，查询大于占比的分区。

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 broker_list Array of DiskusageEntity objects Broker列表。 表4 DiskusageEntity 参数 参数类型 描述 broker_name String Broker名称。 data_disk_size String 磁盘容量。 data_disk_use String 已使用的磁盘容量。 data_disk_free String 剩余可用的磁盘容量。 data_disk_use_percentage String 消息标签。 status String 消息标签。 topic_list Array of DiskusageTopicEntity objects topic磁盘容量使用列表。 表5 DiskusageTopicEntity 参数 参数类型 描述 size String 磁盘使用量。 topic_name String topic名称。 topic_partition String 分区。 percentage Double 磁盘使用量的占比。

URI DELETE /v2/{project_id}/connectors/{connector_id}/sink-tasks/{task_id} 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 项目ID，获取方式请参见获取项目ID。 connector_id 是 String 实例转储ID。 请参考查询实例返回的数据。 task_id 是 String 转储任务ID。

概述 欢迎使用分布式消息服务Kafka版。分布式消息服务Kafka版是一款基于开源社区版Kafka提供的消息队列服务，向用户提供计算、存储和带宽资源独占式的Kafka专享实例。使用分布式消息服务Kafka版，资源按需申请，按需配置Topic的分区与副本数量，即买即用，您将有更多精力专注于业务快速开发，不用考虑部署和运维。 本文档提供了分布式消息服务Kafka版API的描述、语法、参数说明及样例等内容。 分布式消息服务Kafka版持续增加新的功能，将不可避免对现有接口有所调整，比如增加响应参数。 为了减少接口变更带来的影响，除了分布式消息服务Kafka版自身尽量做到接口向下兼容的同时，用户在使用过程中，应当接受出现返回内容（JSON格式）含有未使用的参数和值的现象，即能够正常忽略未使用的参数和值。 父主题： 使用前必读

请求示例 扩容存储空间（按需实例）。 POST https://{endpoint}/v2/{engine}/{project_id}/instances/{instance_id}/extend { "oper_type" : "storage", "new_storage_space" : 600 } 扩容代理数量（按需实例）。 POST https://{endpoint}/v2/{engine}/{project_id}/instances/{instance_id}/extend { "oper_type" : "horizontal", "new_storage_space" : 1600, "new_broker_num" : 4, "tenant_ips" : [ "127.0.0.1", "127.0.0.2", "127.0.0.3" ] } 扩容代理规格（按需实例）。 POST https://{endpoint}/v2/{engine}/{project_id}/instances/{instance_id}/extend { "oper_type" : "vertical", "new_product_id" : "c6.4u8g.cluster" }

请求参数 表2 请求Body参数 参数 是否必选 参数类型 描述 oper_type 是 String 变更类型。 取值范围： storage：存储空间扩容，代理数量不变。 horizontal：代理数量扩容，每个broker的存储空间不变。 vertical：垂直扩容，broker的底层虚机规格变更，代理数量和存储空间不变。 new_storage_space 否 Integer 扩容后的存储空间。 当oper_type类型是storage或horizontal时，该参数有效且必填。 实例存储空间 = 代理数量 * 每个broker的存储空间。 当oper_type类型是storage时，代理数量不变，每个broker存储空间最少扩容100GB。 当oper_type类型是horizontal时，每个broker的存储空间不变。 new_broker_num 否 Integer 当oper_type参数为horizontal时，该参数有效。 取值范围：最多支持30个broker。 new_product_id 否 String 垂直扩容时的新产品ID。 当oper_type类型是vertical时，该参数才有效且必填。 产品ID可以从查询产品规格列表获取。 publicip_id 否 String 实例绑定的弹性IP地址的ID。 以英文逗号隔开多个弹性IP地址的ID。 当oper_type类型是horizontal时，该参数必填。 tenant_ips 否 Array of strings 指定的内网IP地址，仅支持指定IPv4。 指定的IP数量只能小于等于新增节点数量。 当指定IP小于节点数量时，未指定的节点随机分配内网IP地址。 second_tenant_subnet_id 否 String 实例扩容时新节点使用备用子网的id 当实例扩容使用备用子网，则传入此值 需要联系客服添加白名单才能传入此值

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 quotas Array of Quota objects 客户端流控配置列表。 count Integer 用户/客户端流控配置数目。 表4 Quota 参数 参数类型 描述 user String 用户名 client String 客户端ID user-default Boolean 是否使用用户默认设置（是则表示对全部用户限流）。 client-default Boolean 是否使用客户端默认设置（是则表示对全部客户端限流）。 producer-byte-rate Long 生产上限速率（单位为B/s） consumer-byte-rate Long 消费上限速率（单位为B/s）

URI GET /v2/kafka/{project_id}/instances/{instance_id}/kafka-user-client-quota 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 项目ID，获取方式请参见获取项目ID。 instance_id 是 String 实例ID。 表2 Query参数 参数 是否必选 参数类型 描述 offset 否 Integer 偏移量，表示查询该偏移量后面的记录。 最小值：0 最大值：10000 limit 否 Integer 查询返回记录的数量限制。 最小值：1 最大值：50

响应示例 状态码： 200 查询客户端流控配置成功。 { "quotas" : [ { "user" : "", "client" : "", "user-default" : false, "client-default" : true, "producer-byte-rate" : 2097152, "consumer-byte-rate" : 2097152 } ], "count" : 1 }

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 failed_groups Array of failed_groups objects 删除失败的消费组列表。 total Integer 删除失败的个数 表4 failed_groups 参数 参数类型 描述 group_id String 删除失败的消费组ID。 error_message String 删除失败的原因。

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 groups Array of GroupInfoSimple objects 所有的消费组。 total Integer 所有的消费组总数。 表4 GroupInfoSimple 参数 参数类型 描述 createdAt Long 创建时间。 group_id String 消费组ID。 state String 消费组状态。包含以下状态： Dead：消费组内没有任何成员，且没有任何元数据。 Empty：消费组内没有任何成员，存在元数据。 PreparingRebalance：准备开启rebalance。 CompletingRebalance：所有成员加入group。 Stable：消费组内成员可正常消费。 coordinator_id Integer 协调器编号。 group_desc String 消费组描述。 lag Long 堆积数。

响应示例 状态码： 200 查询实例集群的所有消费组成功。 { "groups" : [ { "createdAt" : 1691401194847, "group_id" : "consumer-1", "state" : "EMPTY", "coordinator_id" : 1, "lag" : 0, "group_desc" : null }, { "createdAt" : 1691401194960, "group_id" : "consumer-2", "state" : "STABLE", "coordinator_id" : 2, "lag" : 0, "group_desc" : null }, { "createdAt" : 1691401207309, "group_id" : "consumer-3", "state" : "STABLE", "coordinator_id" : 3, "lag" : 0, "group_desc" : null } ], "total" : 3 }

URI GET /v2/{project_id}/instances/{instance_id}/groups 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 项目ID，获取方式请参见获取项目ID。 instance_id 是 String 实例ID。 表2 Query参数 参数 是否必选 参数类型 描述 offset 否 String 偏移量，表示从此偏移量开始查询， offset大于等于0。 limit 否 String 当次查询返回的最大消费组ID个数，默认值为10，取值范围为1~50。 group 否 String 消费组名过滤查询，过滤方式为字段包含过滤。

响应消息 响应参数 参数说明见表2。 表2 响应参数说明 参数 类型 说明 message object of message 消息列表，见表表3。 表3 message参数 参数 类型 说明 key String 消息的key。 value String 消息内容。 topic String Topic名称。 partition Integer 分区编号。 message_offset Long 消息位置。 size Integer 消息大小，单位字节。 timestamp Long 消息时间戳。 响应示例 { "message": { "topic": "mytest", "partition": 0, "message_offset": 7, "key": null, "value": "kasjdf", "size": 6, "timestamp": 1568125036045 } }