华为云用户手册

请求示例 按标签查询专属主机列表，按标签过滤专属主机，从第一条数据开始查询，搜索名称为resource1的专属主机，标签键为key1值为value1。 POST https://{Endpoint}/v1.0/9c53a566cb3443ab910cf0daebca90c4/dedicated-host-tags/resource_instances/action { "offset": "0", "limit": "100", "action": "filter", "matches": [ { "key": "resource_name", "value": "resource1" } ], "tags": [ { "key": "key1", "values": ["value1"] } ] }

响应示例 action为filter时的响应体： { "resources": [ { "resource_detail": null, "resource_id": "cdfs_cefs_wesas_12_dsad", "resource_name": "resource1", "tags": [ { "key": "key1", "value": "value1" } ] } ], "total_count": 1 } action为count时的响应体： { "total_count": 100 }

URI GET /v1.0/{project_id}/dedicated-host-tags/{dedicated_host_id}/tags 参数说明请参见表1。 表1 参数说明 参数 参数类型 是否必选 描述 project_id String 是 项目ID。 dedicated_host_id String 是 专属主机ID。 可以从专属主机控制台查询，或者通过调用查询专属主机列表API获取。

URI POST /v1.0/{project_id}/dedicated-host-tags/{dedicated_host_id}/tags/action 参数说明请参见表1。 表1 参数说明 参数 参数类型 是否必选 描述 project_id String 是 项目ID。 获取方式请参见获取项目ID。 dedicated_host_id String 是 专属主机ID。 可以从专属主机控制台查询，或者通过调用查询专属主机列表API获取。

请求示例 批量删除专属主机标签，键为key1对应的值为value1，键为key2对应的值为value2。 POST https://{Endpoint}/v1.0/9c53a566cb3443ab910cf0daebca90c4/dedicated-host-tags/74259164-e63a-4ad9-9c77-a1bd2c9aa187/tags/action { "action": "delete", "tags": [ { "key": "key1", "value": "value1" }, { "key": "key2", "value": "value2" } ] }

请求示例 批量添加专属主机标签，键为key1对应的值为value1，键为key2对应的值为value2。 POST https://{Endpoint}/v1.0/9c53a566cb3443ab910cf0daebca90c4/dedicated-host-tags/74259164-e63a-4ad9-9c77-a1bd2c9aa187/tags/action { "action": "create", "tags": [ { "key": "key1", "value": "value1" }, { "key": "key2", "value": "value2" } ] }

URI POST /v1.0/{project_id}/dedicated-host-tags/{dedicated_host_id}/tags/action 参数说明请参见表1。 表1 参数说明 参数 参数类型 是否必选 描述 project_id String 是 项目ID。 获取方式请参见获取项目ID。 dedicated_host_id String 是 专属主机ID。 可以从专属主机控制台查询，或者通过调用查询专属主机列表API获取。

响应示例 { "version": { "id": "v1.0", "links": [ { "href": "https//deh.xxx.com/v1.0/", "rel": "self" } ], "min_version": "", "status": "SUPPORTED", "updated": "2016-12-01T11:33:21Z", "version": "" } }

响应消息 表2 响应参数 参数 参数类型 描述 version Object 专属主机指定API版本信息。 表3 version字段数据结构说明 参数 参数类型 描述 id String API版本ID。 links Array of objects API的url地址。 min_version String 若该版本API支持微版本，则为支持的最小微版本号；如果不支持微版本，则为空。 status String API版本状态： CURRENT：表示该版本为主推版本。 SUPPORTED：表示为老版本，但是现在还在继续支持。 DEPRECATED：表示为废弃版本，存在后续删除的可能。 updated String API版本更新时间。 version String 若该版本API支持微版本，则为支持的最大微版本号；如果不支持微版本，则为空。 表4 links字段数据结构说明 参数 参数类型 描述 href String API的url地址。 rel String API的url地址依赖。

响应消息 表1 响应参数 参数 参数类型 描述 versions Array of objects 专属主机API版本信息列表。 表2 versions字段数据结构说明 参数 参数类型 描述 id String API版本ID。 links Array of objects API的url地址。 min_version String 若该版本API支持微版本，则为支持的最小微版本号；如果不支持微版本，则为空。 status String API版本状态： CURRENT：表示该版本为主推版本。 SUPPORTED：表示为老版本，但是现在还在继续支持。 DEPRECATED：表示为废弃版本，存在后续删除的可能。 updated String API版本更新时间，用UTC时间表示。 version String 若该版本API支持微版本，则为支持的最大微版本号；如果不支持微版本，则为空。 表3 links字段数据结构说明 参数 参数类型 描述 href String API的url地址。 rel String API的url地址依赖。

响应示例 { "versions": [ { "id": "v1.0", "links": [ { "href": "https//deh.xxx.com/v1.0/", "rel": "self" } ], "min_version": "", "status": "SUPPORTED", "updated": "2016-12-01T11:33:21Z", "version": "" } ] }

AK/SK认证 AK/SK签名认证方式仅支持消息体大小在12MB以内，12MB以上的请求请使用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接口获取。 调用本服务API需要项目级别的Token，即调用获取用户Token接口时，请求body中auth.scope的取值需要选择project，如下所示。 { "auth": { "identity": { "methods": [ "password" ], "password": { "user": { "name": $USER_NAME, # IAM 用户名，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全 "password":$PASSWORD, # IAM用户密码，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全 "domain": { "name": $DOMAIN_NAME, # IAM用户所属账号名，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全 } } } }, "scope": { "project": { "name": $PROJECT_NAME, # 项目名称，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全 } } } } 获取Token 后，再调用其他接口时，您需要在请求消息头中添加“X-Auth-Token”，其值即为Token。例如Token值为“ABCDEFJ....”，则调用接口时将“X-Auth-Token: ABCDEFJ....”加到请求消息头即可，如下所示。 1 2 3 POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/projects Content-Type: application/json X-Auth-Token: ABCDEFJ.... 您还可以通过这个视频教程了解如何使用Token认证：https://bbs.huaweicloud.com/videos/101333。

请求消息头 附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头“Content-Type”，请求鉴权信息等。 详细的公共请求消息头字段请参见表3。 表3 公共请求消息头 名称 描述 是否必选 示例 Host 请求的服务器信息，从服务API的URL中获取。值为hostname[:port]。端口缺省时使用默认的端口，https的默认端口为443。 否 使用AK/SK认证时该字段必选。 code.test.com or code.test.com:443 Content-Type 消息体的类型（格式）。推荐用户使用默认值application/json，有其他取值时会在具体接口中专门说明。 是 application/json Content-Length 请求body长度，单位为Byte。 否 3495 X-Project-Id project id，项目编号。请参考获取项目ID章节获取项目编号。 否 如果是专属云场景采用AK/SK认证方式的接口请求，或者多project场景采用AK/SK认证的接口请求，则该字段必选。 e9993fc787d94b6c886cbaa340f9c0f4 X-Auth-Token 用户Token。 用户Token也就是调用获取用户Token接口的响应值，该接口是唯一不需要认证的接口。 请求响应成功后在响应消息头（Headers）中包含的“X-Subject-Token”的值即为Token值。 否 使用Token认证时该字段必选。 注：以下仅为Token示例片段。 MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ API同时支持使用AK/SK认证，AK/SK认证使用SDK对请求进行签名，签名过程会自动往请求中添加Authorization（签名认证信息）和X-Sdk-Date（请求发送的时间）请求头。 AK/SK认证的详细说明请参见认证鉴权的“AK/SK认证”。 对于获取用户Token接口，由于不需要认证，所以只添加“Content-Type”即可，添加消息头后的请求如下所示。 1 2 POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json

请求消息体（可选） 该部分可选。请求消息体通常以结构化格式（如JSON或XML）发出，与请求消息头中Content-Type对应，传递除请求消息头之外的内容。若请求消息体中的参数支持中文，则中文字符必须为UTF-8编码。 每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。 对于获取用户Token接口，您可以从接口的请求部分看到所需的请求参数及参数说明。将消息体加入后的请求如下所示，加粗的斜体字段需要根据实际值填写，其中username为用户名，domainname为用户所属的账号名称，********为用户登录密码，xxxxxxxxxxxxxxxxxx为project的名称，如“cn-north-1”，您可以从地区和终端节点获取。 scope参数定义了Token的作用域，下面示例中获取的Token仅能访问project下的资源。您还可以设置Token的作用域为某个账号下所有资源或账号的某个project下的资源，详细定义请参见获取用户Token。 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json { "auth": { "identity": { "methods": [ "password" ], "password": { "user": { "name": $USER_NAME, # 建议在配置文件或者环境变量中密文存放，使用时解密，确保安全 "password": $PASSWORD, # 建议在配置文件或者环境变量中密文存放，使用时解密，确保安全 "domain": { "name": $DOMAIN_NAME, # 建议在配置文件或者环境变量中密文存放，使用时解密，确保安全 } } } }, "scope": { "project": { "name": $PROJECT_NAME, # 建议在配置文件或者环境变量中密文存放，使用时解密，确保安全 } } } } 到这里为止这个请求需要的内容就具备齐全了，您可以使用curl、Postman或直接编写代码等方式发送请求调用API。对于获取用户Token接口，返回的响应消息头中的“x-subject-token”就是需要获取的用户Token。有了Token之后，您就可以使用Token认证调用其他API。

请求方法 HTTP请求方法（也称为操作或动词），它告诉服务您正在请求什么类型的操作。 表2 HTTP方法 方法 说明 GET 请求服务器返回指定资源。 PUT 请求服务器更新指定资源。 POST 请求服务器新增资源或执行特殊操作。 DELETE 请求服务器删除指定资源，如删除对象等。 HEAD 请求服务器资源头部。 PATCH 请求服务器更新资源的部分内容。 当资源不存在的时候，PATCH可能会去创建一个新的资源。 在获取用户Token的URI部分，您可以看到其请求方法为“POST”，则其请求为： 1 POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens

请求URI 请求URI由如下部分组成： {URI-scheme}://{Endpoint}/{resource-path}?{query-string} 尽管请求URI包含在请求消息头中，但大多数语言或框架都要求您从请求消息中单独传递它，所以在此单独强调。 表1 URI中的参数说明 参数 描述 URI-scheme 表示用于传输请求的协议，当前所有API均采用HTTPS协议。 Endpoint 指定承载REST服务端点的服务器 域名 或IP，不同服务不同区域的Endpoint不同，您可以从地区和终端节点获取。 例如IAM服务在“华北-北京四”区域的Endpoint为“iam.cn-north-4.myhuaweicloud.com”。 resource-path 资源路径，即API访问路径。从具体API的URI模块获取，例如“获取用户Token”API的resource-path为“/v3/auth/tokens”。 query-string 查询参数，是可选部分，并不是每个API都有查询参数。查询参数前面需要带一个“?”，形式为“参数名=参数取值”，例如“?limit=10”，表示查询不超过10条数据。 例如您需要获取IAM在“华北-北京四”区域的Token，则需使用“华北-北京四”区域的Endpoint（iam.cn-north-4.myhuaweicloud.com），并在获取用户Token的URI部分找到resource-path（/v3/auth/tokens），拼接起来如下所示。 1 https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens 图1 URI示意图 为方便查看，在每个具体API的URI部分，只给出resource-path部分，并将请求方法写在一起。这是因为URI-scheme都是HTTPS，而Endpoint在同一个区域也相同，所以简洁起见将这两部分省略。

API概览 目前还未提供购买、删除专属主机的接口，您只能通过管理控制台创建或删除，其他如查询专属主机详情、列表等操作，可以使用接口。 表1 接口说明 类型/接口 说明 查询专属主机列表 查询专属主机列表，可以在URI中增加flavor、dedicated_host_id、state等参数，来过滤查询结果。 查询专属主机详情 查询某一台专属主机的详细信息，例如：专属主机的名称、所属的可用区、可用的vCPU核数、可用的内存大小等。 查询专属主机上的云服务器 查询专属主机上已部署的云服务器信息，例如：云服务器的名称、ID、状态等。 更新专属主机属性 使用该接口可以修改专属主机名称，以及是否开启自动部署功能。开启自动部署后，云服务器可自动调度到这台专属主机上。 查询可用的专属主机类型 查询某一AZ内可用的专属主机类型。 查询API版本信息 查询专属主机当前所有可用的版本信息列表以及指定的版本信息。 专属主机标签管理 为专属主机增删标签，以及按标签搜索专属主机。 配额设置 查询租户的专属主机配额。 在专属主机上创建云服务器的相关接口，请参考《弹性云服务器API参考》。

响应示例 { "quota_set": [ { "used": 0, "resource": "c6", "hard_limit": 5 }, { "used": 0, "resource": "m6", "hard_limit": 5 } ] }

响应示例 { "dedicated_host_types": [ { "host_type": "c6", "host_type_name": "dedicated_general_purpose" }, { "host_type": "m6", "host_type_name": "memory_optimized" } ] }

URI PUT /v1.0/{project_id}/dedicated-hosts/{dedicated_host_id} 参数说明请参见表1。 表1 参数说明 参数 参数类型 是否必选 描述 project_id String 是 项目ID。 获取方式请参见获取项目ID。 dedicated_host_id String 是 专属主机ID。 可以从专属主机控制台查询，或者通过调用查询专属主机列表API获取。

请求消息 表2 请求参数 参数 是否必选 参数类型 描述 dedicated_host 是 Object 专属主机，详情请参见表3 dedicated_host字段数据结构说明。 表3 dedicated_host字段数据结构说明 参数 位置 参数类型 是否必选 描述 auto_placement in String 否 在创建云服务器时（未指定专属主机ID），是否允许云服务器自动分配在一台可用的专属主机上。 取值范围：“on”或“off”。 name in String 否 专属主机名称。

请求示例 更新专属主机属性，在创建云服务器时，不允许云服务器自动分配在一台可用的专属主机上；将专属主机名称更新为DeH_vm3。 PUT https://{Endpoint}/v1.0/9c53a566cb3443ab910cf0daebca90c4/dedicated-hosts/74259164-e63a-4ad9-9c77-a1bd2c9aa187 { "dedicated_host": { "auto_placement": "off", "name": "DeH_vm3" } }

URI GET /v1.0/{project_id}/dedicated-hosts/{dedicated_host_id}/servers 参数说明请参见表1。 表1 参数说明 参数 参数类型 是否必选 描述 project_id String 是 项目ID。 获取方式请参见获取项目ID。 dedicated_host_id String 是 专属主机ID。 可以从专属主机控制台查询，或者通过调用查询专属主机列表API获取。

响应示例 { "servers": [ { "addresses": { "68269e6e-4a27-441b-8029-35373ad50bd9": [ { "addr": "192.168.0.3", "version": 4, "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:1b:35:78", "OS-EXT-IPS:type": "fixed" } ] }, "created": "2012-09-07T16:56:37Z", "flavor": { "id": "1" }, "id": "05184ba3-00ba-4fbc-b7a2-03b62b884931", "metadata": { "os_type": "Linux" }, "name": "new-server-test", "status": "ACTIVE", "tenant_id": "a90b2728805d4240a72cc2eeb4e1244d", "updated": "2012-09-07T16:56:37Z", "user_id": "fake", "task_state": "", "image": { "id": "1ce5800a-e487-4c1b-b264-3353a39e2b4b" } } ] }

响应示例 { "dedicated_host": { "dedicated_host_id": "d465d0ae-f859-4a83-a508-8db654c05e7e", "name": "DEH001", "auto_placement": "off", "availability_zone": "cn-east-3a", "host_properties": { "vcpus": 74, "cores": 22, "sockets": 2, "memory": 151552, "host_type": "c6", "host_type_name": "dedicated_general_purpose", "available_instance_capacities": [ { "flavor": "c6.large.2" }, { "flavor": "c6.xlarge.2" }, { "flavor": "c6.2xlarge.2" }, { "flavor": "c6.3xlarge.2" }, { "flavor": "c6.6xlarge.2" }, { "flavor": "c6.16xlarge.2" } ] }, "state": "available", "project_id": "9c53a566cb3443ab910cf0daebca90c4", "available_vcpus": 20, "available_memory": 40960, "instance_total": 5, "allocated_at": "2016-10-10T14:35:47Z", "released_at": "", "instance_uuids": [ "erf5th66cb3443ab912ff0daebca3456", "23457h66cb3443ab912ff0daebcaer45" ] } }

URI GET /v1.0/{project_id}/dedicated-hosts/{dedicated_host_id} 参数说明请参见表1。 表1 参数说明 参数 参数类型 是否必选 描述 project_id String 是 项目ID。 获取方式请参见获取项目ID。 dedicated_host_id String 是 专属主机ID。 可以从专属主机控制台查询，或者通过调用查询专属主机列表API获取。

响应示例 { "dedicated_hosts": [ { "dedicated_host_id": "d465d0ae-f859-4a83-a508-8db654c05e7e", "name": "DEH001", "auto_placement": "off", "availability_zone": "cn-east-3a", "host_properties": { "vcpus": 74, "cores": 22, "sockets": 2, "memory": 151552, "host_type": "c6", "host_type_name": "dedicated_general_purpose", "available_instance_capacities": [ { "flavor": "c6.large.2" }, { "flavor": "c6.xlarge.2" }, { "flavor": "c6.2xlarge.2" }, { "flavor": "c6.3xlarge.2" }, { "flavor": "c6.6xlarge.2" }, { "flavor": "c6.16xlarge.2" } ] }, "state": "available", "project_id": "9c53a566cb3443ab910cf0daebca90c4", "available_vcpus": 20, "available_memory": 40960, "instance_total": 5, "allocated_at": "2016-10-10T14:35:47Z", "released_at": "" } ], "total": 1 }

请求消息 可以在URI中增加如下参数，来过滤查询结果：host_type、host_type_name、flavor、dedicated_host_id、state、tenant、availability_zone、name、limit、marker、tags、instance_uuid、或者changes-since。 例如：/v1.0/{project_id}/dedicated-hosts?host_type={host_type}&state={state} 表2 请求参数 参数 位置 参数类型 是否必选 描述 dedicated_host_id query String 否 专属主机ID。 name query String 否 专属主机名称。 host_type query String 否 专属主机类型。 host_type_name query String 否 专属主机类型的名称。 flavor query String 否 规格ID。 state query String 否 专属主机状态。 取值范围：“available”、“fault”或“released”。 tenant query String 否 取值范围：租户ID或“all”。 只有具有DeH管理员权限的用户可以指定该参数。 availability_zone query String 否 专属主机所属AZ。 limit query String 否 每个页面上显示的条目数。 marker query String 否 该值是上一页最后一条记录的ID。如果“marker”取值无效，将会返回“400”错误码。 tags query String 否 专属主机标签。 instance_uuid query String 否 专属主机上的云服务器ID。 changes-since query String 否 当专属主机更新了状态时，按日期和时间戳过滤响应。为了便于记录更改，还可能返回最近删除的专属主机。 日期和时间戳的格式为ISO 8601： CCYY-MM-DDThh:mm:ss±hh:mm 如果包含“hh:mm”值，则将时区作为UTC的偏移量返回。例如，“2015-08-27T09:49:58-05:00”。如果您省略时区，则假定为UTC时区。

状态码 正常 返回值 说明 200 OK 服务器已成功处理了请求。 201 Created 请求成功并且服务器创建了新的资源。 202 Accepted 服务器已接受请求，延迟处理。 204 No Content 服务器成功处理了请求，但没有返回任何内容。 异常 返回值 说明 400 Bad Request 服务器未能处理请求。 401 Unauthorized 被请求的页面需要用户名和密码。 403 Forbidden 对被请求页面的访问被禁止。 404 Not Found 服务器无法找到被请求的页面。 405 Method Not Allowed 请求中指定的方法不被允许。 406 Not Acceptable 服务器生成的响应无法被客户端所接受。 407 Proxy Authentication Required 用户必须首先使用代理服务器进行验证，这样请求才会被处理。 408 Request Timeout 请求超出了服务器的等待时间。 409 Conflict 由于冲突，请求无法被完成。 500 Internal Server Error 请求未完成。服务异常。 501 Not Implemented 请求未完成。服务器不支持所请求的功能。 502 Bad Gateway 请求未完成。服务器从上游服务器收到一个无效的响应。 503 Service Unavailable 请求未完成。系统暂时异常。 504 Gateway Timeout 网关超时。 父主题： 公共参数