华为云用户手册

AK/SK认证 AK/SK签名认证方式仅支持消息体大小12M以内，12M以上的请求请使用Token认证。 AK/SK认证就是使用AK/SK对请求进行签名，在请求时将签名信息添加到消息头，从而通过身份认证。 AK(Access Key ID)：访问密钥ID。与私有访问密钥关联的唯一标识符；访问密钥ID和私有访问密钥一起使用，对请求进行加密签名。 SK(Secret Access Key)：与访问密钥ID结合使用的密钥，对请求进行加密签名，可标识发送方，并防止请求被修改。 使用AK/SK认证时，您可以基于签名算法使用AK/SK对请求进行签名，也可以使用专门的签名SDK对请求进行签名。详细的签名方法和SDK使用方法请参见API签名指南。 签名SDK只提供签名功能，与服务提供的SDK不同，使用时请注意。

Token认证 Token的有效期为24小时，需要使用一个Token鉴权时，可以先缓存起来，避免频繁调用。 Token在计算机系统中代表令牌（临时）的意思，拥有Token就代表拥有某种权限。Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得操作API的权限。Token可通过调用获取用户Token接口获取。 云服务存在两种部署方式：项目级服务和全局级服务。其中： 项目级服务需要获取项目级别的Token，此时请求body中auth.scope的取值为project。 全局级服务需要获取全局级别的Token，此时请求body中auth.scope的取值为domain。 调用本服务API需要project级别的Token，即调用获取用户Token接口时，请求body中auth.scope的取值需要选择project，如下所示。 { "auth": { "identity": { "methods": [ "password" ], "password": { "user": { "name": "username", "password": "********", "domain": { "name": "domainname" } } } }, "scope": { "project": { "name": "xxxxxxxx" } } } } 获取Token 后，再调用其他接口时，您需要在请求消息头中添加“X-Auth-Token”，其值即为Token。例如Token值为“ABCDEFJ....”，则调用接口时将“X-Auth-Token: ABCDEFJ....”加到请求消息头即可，如下所示。 POST https://iam.cn-north-4.myhuaweicloud.com/v3/auth/projects Content-Type: application/json X-Auth-Token: ABCDEFJ.... 您还可以通过这个视频教程了解如何使用Token认证：https://bbs.huaweicloud.com/videos/101333。

请求示例 创建一个按需付费的Kafka实例，版本为2.7，规格为2U4G*3，300GB的存储空间。 POST https://{endpoint}/v2/{engine}/{project_id}/instances { "name" : "kafka-test", "description" : "", "engine" : "kafka", "engine_version" : "2.7", "storage_space" : 300, "vpc_id" : "********-9b4a-44c5-a964-************", "subnet_id" : "********-8fbf-4438-ba71-************", "security_group_id" : "********-e073-4aad-991f-************", "available_zones" : [ "********706d4c1fb0eb72f0********" ], "product_id" : "c6.2u4g.cluster", "ssl_enable" : true, "kafka_security_protocol" : "SASL_SSL", "sasl_enabled_mechanisms" : [ "SC RAM -SHA-512" ], "storage_spec_code" : "dms.physical.storage.ultra.v2", "broker_num" : 3, "arch_type" : "X86", "enterprise_project_id" : "0", "access_user" : "********", "password" : "********", "enable_publicip" : true, "tags" : [ { "key" : "aaa", "value" : "111" } ], "retention_policy" : "time_base", "disk_encrypted_enable" : true, "disk_encrypted_key" : "********-b953-4875-a743-************", "publicip_id" : "********-88fc-4a8c-86d0-************,********-16af-455d-8d54-************,********-3d69-4367-95ab-************", "vpc_client_plain" : true, "enable_auto_topic" : true } 创建一个包年包月的Kafka实例，版本为2.7，规格为2U4G*3，300GB的存储空间。 POST https://{endpoint}/v2/{engine}/{project_id}/instances { "name" : "kafka-test1", "description" : "", "engine" : "kafka", "engine_version" : "2.7", "storage_space" : 300, "vpc_id" : "********-9b4a-44c5-a964-************", "subnet_id" : "********-8fbf-4438-ba71-************", "security_group_id" : "********-e073-4aad-991f-************", "available_zones" : [ "********706d4c1fb0eb72f0********" ], "product_id" : "c6.2u4g.cluster", "ssl_enable" : true, "kafka_security_protocol" : "SASL_SSL", "sasl_enabled_mechanisms" : [ "SCRAM-SHA-512" ], "storage_spec_code" : "dms.physical.storage.ultra.v2", "broker_num" : 3, "arch_type" : "X86", "enterprise_project_id" : "0", "access_user" : "********", "password" : "********", "enable_publicip" : true, "tags" : [ { "key" : "aaa", "value" : "111" } ], "retention_policy" : "time_base", "publicip_id" : "********-88fc-4a8c-86d0-************,********-16af-455d-8d54-************,********-3d69-4367-95ab-************", "vpc_client_plain" : true, "enable_auto_topic" : true, "bss_param" : { "charging_mode" : "prePaid", "period_type" : "month", "period_num" : 1, "is_auto_pay" : true } }

请求参数 表2 请求Body参数 参数 是否必选 参数类型 描述 topics 是 Array of AccessPolicyTopicEntity objects topic列表。 表3 AccessPolicyTopicEntity 参数 是否必选 参数类型 描述 name 是 String topic名称。 policies 是 Array of AccessPolicyEntity objects 权限列表。 表4 AccessPolicyEntity 参数 是否必选 参数类型 描述 user_name 否 String 用户名称。 设置用户权限时，为必选参数。 access_policy 否 String 权限类型。 all：拥有发布、订阅权限; pub：拥有发布权限; sub：拥有订阅权限。 设置用户权限时，为必选参数。

请求示例 设置用户权限，为root用户授予发布和订阅topic-test的权限。 POST https://{endpoint}/v1/{project_id}/instances/{instance_id}/topics/accesspolicy { "topics" : [ { "name" : "topic-test", "policies" : [ { "user_name" : "root", "access_policy" : "all" } ] } ] }

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

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

标签管理 表9 标签管理 权限 对应API接口 授权项 IAM 项目(Project) 企业项目(Enterprise Project) 批量添加或删除实例标签 POST /v2/{project_id}/kafka/{instance_id}/tags/action dms:instance:modify √ √ 查询实例标签 GET /v2/{project_id}/kafka/{instance_id}/tags dms:instance:get √ √ 查询项目标签 GET /v2/{project_id}/kafka/tags dms:instance:get √ √

用户管理 表6 用户管理 权限 对应API接口 授权项 IAM项目(Project) 企业项目(Enterprise Project) 查询用户列表 GET /v2/{project_id}/instances/{instance_id}/users dms:instance:get √ √ 创建用户 POST /v2/{project_id}/instances/{instance_id}/users dms:instance:modify √ √ 批量删除用户 PUT /v2/{project_id}/instances/{instance_id}/users dms:instance:modify √ √ 重置用户密码 PUT /v2/{project_id}/instances/{instance_id}/users/{user_name} dms:instance:get √ √ 查询用户权限 GET /v1/{project_id}/instances/{instance_id}/topics/{topic_name}/accesspolicy dms:instance:get √ √ 设置用户权限 POST /v1/{project_id}/instances/{instance_id}/topics/accesspolicy dms:instance:modify √ √

后台任务管理 表8 后台任务管理 权限 对应API接口 授权项 IAM项目(Project) 企业项目(Enterprise Project) 查询实例的后台任务列表 GET /v2/{project_id}/instances/{instance_id}/tasks dms:instance:getBackgroundTask √ √ 查询后台任务管理中的指定记录 GET /v2/{project_id}/instances/{instance_id}/tasks/{task_id} dms:instance:getBackgroundTask √ √ 删除后台任务管理中的指定记录 DELETE /v2/{project_id}/instances/{instance_id}/tasks/{task_id} dms:instance:deleteBackgroundTask √ √

生命周期管理 表1 生命周期管理 权限 对应API接口 授权项（Action） IAM项目 (Project) 企业项目 (Enterprise Project) 创建实例 POST /v2/{engine}/{project_id}/instances dms:instance:create √ √ 查询所有实例列表 GET /v2/{project_id}/instances dms:instance:list √ √ 查询指定实例 GET /v2/{project_id}/instances/{instance_id} dms:instance:get √ √ 删除指定的实例 DELETE /v2/{project_id}/instances/{instance_id} dms:instance:delete √ √ 修改实例信息 PUT /v2/{project_id}/instances/{instance_id} dms:instance:modify √ √ 批量重启或删除实例 POST /v2/{project_id}/instances/action 重启：dms:instance:modifyStatus 删除：dms:instance:delete √ √

实例管理 表2 实例管理 权限 对应API接口 授权项（Action） IAM项目 (Project) 企业项目 (Enterprise Project) 重置密码 POST /v2/{project_id}/instances/{instance_id}/password dms:instance:resetAuthInfo √ √ 重置Manager密码 PUT /v2/{project_id}/instances/{instance_id}/kafka-manager-password dms:instance:resetAuthInfo √ √ 重启Manager PUT /v2/{project_id}/instances/{instance_id}/restart-kafka-manager dms:instance:modifyStatus √ √ 开启或关闭实例自动创建topic功能 POST /v2/{project_id}/instances/{instance_id}/autotopic dms:instance:modify √ √ 修改实例跨VPC访问的内网IP POST /v2/{project_id}/instances/{instance_id}/crossvpc/modify dms:instance:modify √ √ 重置消费组消费进度到指定位置 POST /v2/{project_id}/instances/{instance_id}/management/groups/{group}/reset-message-offset dms:instance:modify √ √

主题管理 表5 主题管理 权限 对应API接口 授权项 IAM项目(Project) 企业项目(Enterprise Project) Kafka实例创建Topic POST /v2/{project_id}/instances/{instance_id}/topics dms:instance:modify √ √ Kafka实例查询Topic GET /v2/{project_id}/instances/{instance_id}/topics dms:instance:get √ √ 修改Kafka实例Topic PUT /v2/{project_id}/instances/{instance_id}/topics dms:instance:modify √ √ Kafka实例批量删除Topic POST /v2/{project_id}/instances/{instance_id}/topics/delete dms:instance:modify √ √

转储管理 表3 转储管理 权限 对应API接口 授权项 IAM项目(Project) 企业项目(Enterprise Project) 创建实例的转储节点 POST /v2/{project_id}/instances/{instance_id}/connector dms:instance:connector √ √ 创建转储任务 POST /v2/{project_id}/connectors/{connector_id}/sink-tasks dms:instance:createConnectorSinkTask √ √ 查询转储任务列表 GET /v2/{project_id}/connectors/{connector_id}/sink-tasks dms:instance:listConnectorSinkTask √ √ 修改转储任务的配额 PUT /v2/{project_id}/connectors/{connector_id}/sink-tasks dms:instance:createConnectorSinkTask √ √ 查询单个转储任务 GET /v2/{project_id}/connectors/{connector_id}/sink-tasks/{task_id} dms:instance:getConnectorSinkTask √ √ 删除单个转储任务 POST /v2/{project_id}/connectors/{connector_id}/sink-tasks/{task_id} dms:instance:deleteConnectorSinkTask √ √

支持的授权项 策略包含系统策略和自定义策略，如果系统策略不满足授权要求，管理员可以创建自定义策略，并通过给用户组授予自定义策略来进行精细的访问控制。策略支持的操作与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实例节点的连通性是否正常。