创建云硬盘_云硬盘 EVS_API参考_API v2_云硬盘_华为云

(1)

API 参考

文档版本 22

发布日期 2019-09-09

(2)

非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。

商标声明

和其他华为商标均为华为技术有限公司的商标。

本文档提及的其他所有商标或注册商标，由各自的所有人拥有。

注意

您购买的产品、服务或特性等应受华为公司商业合同和条款的约束，本文档中描述的全部或部分产品、服务或特性可能不在您的购买或使用范围之内。除非合同另有约定，华为公司对本文档内容不做任何明示或暗示的声明或保证。

由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文档中的所有陈述、信息和建议不构成任何明示或暗示的担保。

华为技术有限公司

地址：深圳市龙岗区坂田华为总部办公楼邮编：518129

网址：

https://www.huawei.com

客户服务邮箱：

[email protected]

客户服务电话：4008302118

(3)

1 ^{使用前必读}

1.1 概述

欢迎使用云硬盘（Elastic Volume Service, EVS）。云硬盘可以为云服务器提供高可靠、高性能、规格丰富并且可弹性扩展的块存储服务，可满足不同场景的业务需求，

适用于分布式文件系统、开发测试、数据仓库以及高性能计算等场景。

您可以使用本文档提供API对云硬盘进行相关操作，如创建、查询、删除、更新等。支持的全部操作请参见API概览。

在调用云硬盘API之前，请确保已经充分了解云硬盘相关概念，详细信息请参见《云硬盘用户指南》的“产品介绍”。

1.2 调用说明

云硬盘提供了REST（Representational State Transfer）风格API，支持您通过HTTPS 请求调用，调用方法请参见如何调用API。

同时云硬盘还提供多种编程语言的SDK供您使用，SDK的使用方法请参见https://

sdkcenter.developer.huaweicloud.com/zh-cn。

1.3 终端节点（Endpoint）

终端节点（Endpoint）即调用API的请求地址，不同服务不同区域的终端节点不同，您可以从地区和终端节点中查询云硬盘服务的终端节点。

1.4 约束与限制

● 您能创建的云硬盘资源的数量与配额有关系，如果您想查看服务配额、扩大配额，具体请参见“查看云硬盘资源配额”。

● 更详细的限制请参见具体API的说明。

(9)

1.5 基本概念

● 帐号

用户注册时的帐号，帐号对其所拥有的资源及云服务具有完全的访问权限，可以重置用户密码、分配用户权限等。由于帐号是付费主体，为了确保帐号安全，建议您不要直接使用帐号进行日常管理工作，而是创建用户并使用他们进行日常管理工作。

● 用户

由帐号在IAM中创建的用户，是云服务的使用人员，具有身份凭证（密码和访问密钥）。

在我的凭证下，您可以查看帐号ID和IAM用户ID。通常在调用API的鉴权过程中，

您需要用到帐号、用户和密码等信息。

● 区域（Region）

从地理位置和网络时延维度划分，同一个Region内共享弹性计算、块存储、对象存储、VPC网络、弹性公网IP、镜像等公共服务。Region分为通用Region和专属 Region，通用Region指面向公共租户提供通用云服务的Region；专属Region指只承载同一类业务或只面向特定租户提供业务服务的专用Region。

详情请参见区域和可用区。

● 可用区（AZ，Availability Zone）

一个可用区是一个或多个物理数据中心的集合，有独立的风火水电，AZ内逻辑上再将计算、网络、存储等资源划分成多个集群。一个Region中的多个AZ间通过高速光纤相连，以满足用户跨AZ构建高可用性系统的需求。

● 项目

区域默认对应一个项目，这个项目由系统预置，用来隔离物理区域间的资源（计算资源、存储资源和网络资源），以默认项目为单位进行授权，用户可以访问您帐号中该区域的所有资源。如果您希望进行更加精细的权限控制，可以在区域默认的项目中创建子项目，并在子项目中创建资源，然后以子项目为单位进行授权，使得用户仅能访问特定子项目中资源，使得资源的权限控制更加精确。

图1-1 项目隔离模型

同样在我的凭证下，您可以查看项目ID。

● 企业项目

企业项目是项目的升级版，针对企业不同项目间资源的分组和管理，是逻辑隔离。企业项目中可以包含多个区域的资源，且项目中的资源可以迁入迁出。

(10)

关于企业项目ID的获取及企业项目特性的详细信息，请参见《企业管理用户指

南》。

1.6 API 版本选择建议

API 风格说明

当前EVS服务对外的API存在以下两种风格：

● EVS服务自定义规范的API，以下简称为EVS自定义API。

● 顺从OpenStack社区标准原生规范的API，以下简称为OpenStack Cinder API。

两者风格不同，功能相近。OpenStack Cinder API主要用于满足您在开源生态工具方面的对接需求。针对某些功能，EVS自定义API在OpenStack Cinder API基础上，做了功能增强。

● 支持创建包周期的云硬盘

● 支持扩容包周期的云硬盘

● 支持企业项目管理

版本号介绍

EVS自定义API提供了多个版本。在接口功能相同的情况下，推荐您优先使用v2接口。

同时，针对创建、扩容云硬盘，还提供了v2.1接口，可以针对包周期云硬盘执行相关操作。

OpenStack Cinder API提供v2和v3版本，其中v3支持微版本号。

(11)

2 ^{API 概览}

云硬盘所提供的接口分为EVS自定义API与OpenStack Cinder API。

通过配合使用EVS自定义API与OpenStack Cinder API，您可以完整的使用云硬盘的所有功能。此外，部分扩展接口提供了基于企业项目的授权功能，具体在该接口的功能介绍中有描述，如果您需要使用企业项目授权功能，建议您调用这部分接口。

表2-1 接口说明

类型子类型说明

API 云硬盘该部分API提供云硬盘的创建、删除、云硬盘详情查

询等操作。

云硬盘快照云硬盘快照指的是云硬盘数据在某个时刻的完整拷贝或镜像。

该部分API提供回滚快照数据至云硬盘的操作。

云硬盘标签标签用于标识云资源，可通过标签实现对云资源的分类和搜索。

该部分API提供云硬盘标签的添加、删除、查询等操作。

OpenStack

Cinder API 云硬盘该部分API提供云硬盘的创建、更新、云硬盘列表查询、镜像列表查询、租户配额查询等操作。

云硬盘Action 该部分API提供云硬盘的扩容、保留、导出镜像、设置启动盘表示等操作。

云硬盘快照云硬盘快照指的是云硬盘数据在某个时刻的完整拷贝或镜像。

该部分API提供云硬盘快照的创建、快照列表查询、

快照元数据更新、快照元数据查询等操作。

云硬盘过户通过云硬盘过户功能把一个租户的云硬盘过户给另一个租户，过户成功后，该云硬盘就属于接受过户的租户。

该部分API提供云硬盘过户的创建、接受、删除、过户记录查询等操作。

(12)

3 ^{如何调用 API}

3.1 构造请求

本节介绍REST API请求的组成，并以调用IAM服务的获取用户Token说明如何调用 API，该API获取用户的Token，Token可以用于调用其他API时鉴权。

您还可以通过这个视频教程了解如何构造请求调用API：https://

bbs.huaweicloud.com/videos/102987。

请求 URI

请求URI由如下部分组成：

{URI-scheme}://{Endpoint}/{resource-path}?{query-string}

尽管请求URI包含在请求消息头中，但大多数语言或框架都要求您从请求消息中单独传递它，所以在此单独强调。

表3-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条数据。

(13)

例如您需要获取IAM在“华北-北京四”区域的Token，则需使用“华北-北京四”区域的Endpoint（iam.cn-north-4.myhuaweicloud.com），并在获取用户Token的URI部分找到resource-path（/v3/auth/tokens），拼接起来如下所示。

https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens

图3-1 URI 示意图

说明

为查看方便，在每个具体API的URI部分，只给出resource-path部分，并将请求方法写在一起。

这是因为URI-scheme都是HTTPS，而Endpoint在同一个区域也相同，所以简洁起见将这两部分省略。

请求方法

HTTP请求方法（也称为操作或动词），它告诉服务你正在请求什么类型的操作。

表3-2 HTTP 方法

方法说明

GET 请求服务器返回指定资源。

PUT 请求服务器更新指定资源。

POST 请求服务器新增资源或执行特殊操作。

DELETE 请求服务器删除指定资源，如删除对象等。

HEAD 请求服务器资源头部。

PATCH 请求服务器更新资源的部分内容。

当资源不存在的时候，PATCH可能会去创建一个新的资源。

在获取用户Token的URI部分，您可以看到其请求方法为“POST”，则其请求为：

POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens

请求消息头

附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头“Content-Type”，请求鉴权信息等。

详细的公共请求消息头字段请参见表3-3。

(14)

表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认证的接口请求，则该字段必选。

e9993fc787d94b6c886cb aa340f9c0f4

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（请求发送的时间）请求头。

(15)

对于获取用户Token接口，由于不需要认证，所以只添加“Content-Type”即可，添加消息头后的请求如下所示。

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。

POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json

{ "auth": { "identity": { "methods": [ "password"

],

"password": { "user": {

"name": "username", "password": "********", "domain": {

"name": "domainname"

} } } }, "scope": { "project": {

"name": "xxxxxxxxxxxxxxxxxx"

} } } }

到这里为止这个请求需要的内容就具备齐全了，您可以使用curl、Postman或直接编写代码等方式发送请求调用API。对于获取用户Token接口，返回的响应消息头中“x- subject-token”就是需要获取的用户Token。有了Token之后，您就可以使用Token认证调用其他API。

(16)

3.2 认证鉴权

调用接口有如下两种认证方式，您可以选择其中一种进行认证鉴权。

● Token认证：通过Token认证调用请求。

● AK/SK认证：通过AK（Access Key ID）/SK（Secret Access Key）加密调用请求。

推荐使用AK/SK认证，其安全性比Token认证要高。

Token 认证

说明

Token的有效期为24小时，需要使用一个Token鉴权时，可以先缓存起来，避免频繁调用。

Token在计算机系统中代表令牌（临时）的意思，拥有Token就代表拥有某种权限。

Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得操作API的权限。Token可通过调用获取用户Token接口获取。

云服务存在两种部署方式：项目级服务和全局级服务。其中：

● 项目级服务需要获取项目级别的Token，此时请求body中auth.scope的取值为 project。

● 全局级服务需要获取全局级别的Token，此时请求body中auth.scope的取值为 domain。

调用本服务API需要项目级别的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-1.myhuaweicloud.com/v3/auth/projects

(17)

您还可以通过这个视频教程了解如何使用Token认证：https://

bbs.huaweicloud.com/videos/101333。

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不同，使用时请注意。

3.3 返回结果

状态码

请求发送以后，您会收到响应，包含状态码、响应消息头和消息体。

状态码是一组从1xx到5xx的数字代码，状态码表示了请求响应的状态，完整的状态码列表请参见状态码。

对于获取用户Token接口，如果调用后返回状态码为“201”，则表示请求成功。

响应消息头

对应请求消息头，响应同样也有消息头，如“Content-type”。

对于获取用户Token接口，返回如图3-2所示的消息头，其中“x-subject-token”就是需要获取的用户Token。有了Token之后，您就可以使用Token认证调用其他API。

(18)

图3-2 获取用户 Token 响应消息头

响应消息体（可选）

该部分可选。响应消息体通常以结构化格式（如JSON或XML）返回，与响应消息头中 Content-Type对应，传递除响应消息头之外的内容。

对于获取用户Token接口，返回如下消息体。为篇幅起见，这里只展示部分内容。

{ "token": {

"expires_at": "2019-02-13T06:52:13.855000Z", "methods": [

"password"

],

"catalog": [ {

"endpoints": [ {

"region_id": "az-01", ...

当接口调用出错时，会返回错误码及错误信息说明，错误响应的Body体格式如下所示。

{ "error_msg": "The format of message is error", "error_code": "AS.0001"

}

其中，error_code表示错误码，error_msg表示错误描述信息。

(19)

4 ^快速入门

4.1 创建云硬盘

操作场景

本章节指导用户通过API创建云硬盘。API的调用方法请参见如何调用API。

以从快照创建云硬盘为例。

前提条件

您需要规划云硬盘所在的区域信息，并根据区域确定调用API的Endpoint，详细信息请参见终端节点（Endpoint）。

操作步骤

步骤1 从快照创建云硬盘，请先查询云硬盘快照列表，获取快照信息。

API：查询云硬盘快照详细列表信息

● 请求样例

GET https://{endpoint}/v2/ba546eb46e7247c9aadb566ed7a1d31f/

cloudsnapshots/detail

● 响应样例

{ "count": 1, "snapshots": [ {

"status": "available", "description": null, "metadata": {}, "size": 40,

"id": "0b126d3b-f2af-404d-8d39-a42fce70065a", "name": "snapshot-test",

"created_at": "2019-06-18T12:47:33.700070", "updated_at": "2019-06-18T12:47:38.234689", "volume_id": "037cf89a-8cea-4d63-ac57-345c0ffccfc2",

"os-extended-snapshot-attributes:project_id": "ba546eb46e7247c9aadb566ed7a1d31f", "os-extended-snapshot-attributes:progress": "100%",

"service_type": "EVS"

(20)

} ]}

回显中的“id”即为快照的ID。

步骤2 通过快照ID创建云硬盘。

API：创建云硬盘

● 请求样例

POST https://{endpoint}/v2.1/ba546eb46e7247c9aadb566ed7a1d31f/

cloudvolumes

{ "volume": { "count": 1,

"availability_zone": "az-dc-1", "description": "test_volume_1", "size": 120,

"snapshot_id": "0b126d3b-f2af-404d-8d39-a42fce70065a", "name": "test_volume_1",

"volume_type": "SATA"

} }

● 响应样例

{ "job_id": "ff8080816b512df7016b6ab8982b496b"

}

----结束

(21)

5 API 版本信息查询

5.1 查询接口版本信息列表

功能介绍

查询接口版本信息列表。

调试

您可以在API Explorer中直接运行调试该接口。

URI

● URI格式 GET /

请求消息

● 请求样例：

GET https://{endpoint}/

响应消息

● 响应参数

参数参数类型描述

versions Array of

objects 接口版本信息列表，请参见•versions参数说

明。

● versions参数说明

min_version String 接口版本支持的最小微版本号。若该版本不支持微版本，则为空字符串。

(22)

参数参数类型描述 media-types Array of

objects 接口版本的请求消息类型信息，请参见

•media-types参数说明。

links Array of

objects 接口版本信息的URI描述信息，请参见•links

参数说明。

id String 接口版本的ID。

updated String 接口版本更新时间。

时间格式：UTC YYYY-MM- DDTHH:MM:SS.XXXXXX

version String 接口版本支持的最大微版本号。若该版本不支持微版本，则为空字符串。

status String 接口版本的状态。存在以下状态：

● CURRENT：表示该版本为主推版本。

● SUPPORTED：表示为老版本，但是现在还在继续支持。

● DEPRECATED：表示为废弃版本，存在后续删除的可能。

● media-types参数说明

名称参数类型描述

type String 返回类型

base String 文本类型

● links参数说明

参数名参数类型描述

rel String 域名的描述

href String 域名

● 响应样例

{ "versions": [ {

"min_version": "", "media-types": [ {

"type": "application/vnd.openstack.volume+json;version=1", "base": "application/json"

}, {

(23)

} ], "links": [ {

"rel": "describedby",

"href": "http://docs.openstack.org/", "type": "text/html"

}, {

"rel": "self",

"href": "https://evs.localdomain.com/v1"

} ],

"id": "v1.0",

"updated": "2014-06-28T12:20:21Z", "version": "",

"status": "SUPPORTED"

}, {

"type": "application/vnd.openstack.volume+xml;version=1", "base": "application/xml"

} ], "links": [ {

}, {

"rel": "self",

} ],

"id": "v2.0",

}, {

"min_version": "3.0", "media-types": [ {

}, {

} ], "links": [ {

}, {

"rel": "self",

} ],

(24)

"id": "v3.0",

"updated": "2016-02-08T12:20:21Z", "version": "3.0",

"status": "CURRENT"

} ] }

状态码

● 正常 300

错误码

请参考错误码。

5.2 查询接口的版本信息

功能介绍

查询API接口的版本信息。

调试

您可以在API Explorer中直接运行调试该接口。

URI

● URI格式

GET /{api_version}

● 参数说明

api_version String 查询的目标版本号。

取值为：v1、v2、v3。

请求消息

● 请求样例：

GET https://{endpoint}/v2

响应消息

● 响应参数

versions Array of

objects 接口版本信息列表，请参见•versions参数说

明。

(25)

● versions参数说明

min_version String 接口版本支持的最小微版本号。若该版本不支持微版本，则为空字符串。

media-types Array of

objects 接口版本的请求消息类型信息，请参见

•media-types参数说明。

links Array of

objects 接口版本信息的URI描述信息，请参见•links

参数说明。

id String 接口版本的ID。

updated String 接口版本更新时间。

时间格式：UTC YYYY-MM- DDTHH:MM:SS.XXXXXX

version String 接口版本支持的最大微版本号。若该版本不支持微版本，则为空字符串。

status String 接口版本的状态。存在以下状态：

● CURRENT：表示该版本为主推版本。

● SUPPORTED：表示为老版本，但是现在还在继续支持。

● DEPRECATED：表示为废弃版本，存在后续删除的可能。

● media-types参数说明

base String 文本类型

● links参数说明

rel String 域名的描述

href String 域名

● 响应样例

{ "versions": [ {

"type": "application/vnd.openstack.volume+json;version=1",

(26)

"base": "application/json"

}, {

} ], "links": [ {

}, {

"rel": "self",

} ],

"id": "v2.0",

} ] }

状态码

● 正常 200

错误码

请参考错误码。

(27)

6 ^{API v2}

6.1 云硬盘

6.1.1 创建云硬盘

功能介绍

创建按需或包周期云硬盘。在创建包周期云硬盘的场景下：

● 如果您需要查看订单可用的优惠券，请参考"查询订单可用优惠券"。

● 如果您需要支付订单，请参考"支付包周期产品订单"。

● 如果您需要查询订单的资源开通详情，请参考"查询订单的资源开通详情"。

● 如果您需要退订该包周期资源，请参考“退订包周期资源”。

调试

您可以在API Explorer中调试该接口。

URI

POST /v2.1/{project_id}/cloudvolumes

表6-1 路径参数

参数是否必选参数类型描述

project_id 是 String 项目ID。获取方法请参见"获取

项目ID"。

(28)

请求参数

表6-2 请求 Header 参数

X-Auth-Token 是 String 用户Token。通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。

表6-3 请求 Body 参数

bssParam 否 BssParamFor CreateVolum e object

按需和包周期的扩展参数

volume 是 CreateVolum eOption object

待创建的云硬盘信息

server_id 否 String 创建云硬盘并挂载到目标虚拟

机。创建的云硬盘的计费模式会与虚拟机的计费模式保持一致。目前只支持ECS服务的虚拟机，暂不支持BMS的裸金属服务器。

OS-SCH- HNT:schedule r_hints

否 CreateVolum

eSchedulerHi nts object

云硬盘调度参数，可用于指定云硬盘创建到某个专属存储池中

表6-4 BssParamForCreateVolume

chargingMod

e 否 String 功能说明：计费模式。默认值为

postPaid。取值范围：

● prePaid：包年包月

● postPaid：按需缺省值：postPaid 枚举值：

● postPaid

● prePaid

(29)

isAutoPay 否 String 功能说明：是否立即支付。

chargingMode为PrePaid时该参数会生效。默认值为false。取值范围：

● true：立即支付，从帐户余额中自动扣费

● false：不立即支付，创建订单暂不支付

缺省值：false 枚举值：

● true

● false

isAutoRenew 否 String 功能说明：是否自动续订。

chargingMode为prePaid时该参数会生效。默认值为false。取值范围：

● true：自动续订，自动续订周期与订购周期相同

● false：不自动续订缺省值：false 枚举值：

● true

● false

periodNum 否 Integer 功能说明：订购周期数，

chargingMode为prePaid时该参数会生效，并且该参数为为必选。取值范围：

● periodType为month时，为 [1-9]

● periodType为year时，为 [1-1]

periodType 否 String 功能说明：订购周期单位。

chargingMode为prePaid时该参数会生效，并且该参数为必选。

取值范围：

● month：月

● year：年枚举值：

● month

● year

(30)

表6-5 CreateVolumeOption

availability_zo

ne 是 String 指定要创建云硬盘的可用区。

backup_id 否 String 备份ID，从备份创建云硬盘时为必选。

count 否 Integer 批量创云硬盘的个数。如果无该

参数，表明只创建1个云硬盘，

目前最多支持批量创建100个。

从备份创建云硬盘时，不支持批量创建，数量只能为“1”。

如果发送请求时，将参数值设置为小数，则默认取小数点前的整数。

description 否 String 云硬盘的描述。最大支持255个字节。

enterprise_pro

ject_id 否 String 企业项目ID。创建云硬盘时，给

云硬盘绑定企业项目ID。

imageRef 否 String 镜像ID，指定该参数表示创建云

硬盘方式为从镜像创建云硬盘。

(31)

参数是否必选参数类型描述 metadata 否 Map<String,St

ring> 创建云硬盘的metadata信息可选参数如下:

[__system__cmkid]metadata中的加密cmkid字段，与

__system__encrypted配合表示需要加密，cmkid长度固定为36 个字节。

说明请求获取密钥ID的方法请参考："查询密钥列表"。

[__system__encrypted]metada ta中的表示加密功能的字段,0代表不加密,1代表加密。不指定该字段时,云硬盘的加密属性与数据源保持一致,如果不是从数据源创建的场景,则默认不加密。

[full_clone]从快照创建云硬盘时，如需使用link克隆方式，请指定该字段的值为0。

[hw:passthrough]

● true表示云硬盘的设备类型为SCSI类型，即允许ECS操作系统直接访问底层存储介质。支持SCSI锁命令。

● false表示云硬盘的设备类型为VBD (虚拟块存储设备 , Virtual Block Device)类型，

即为默认类型，VBD只能支持简单的SCSI读写命令。

● 该字段不存在时，云硬盘默认为VBD类型。

[create_for_volume_id]

● true表示接口响应中会通过 volume_ids字段返回本次创建的云硬盘ID。

● false表示接口响应中不会返回本次创建的云硬盘ID。

该字段不存在时，默认为 false。

multiattach 否 Boolean 是否为共享云硬盘。true为共享盘，false为普通云硬盘。

(32)

name 否 String 云硬盘名称。如果为创建单个

云硬盘，name为云硬盘名称。

最大支持255个字节。创建的云硬盘数量（count字段对应的值）大于1时，为区分不同云硬盘，创建过程中系统会自动在名称后加“-0000”的类似标记。

例如：volume-0001、

volume-0002。最大支持250个字节。

size 是 Integer 云硬盘大小，单位为GB，其限

制如下：系统盘：

1GB-1024GB 数据盘：

10GB-32768GB 创建空白云硬盘和从镜像/快照创建云硬盘时，size为必选，且云硬盘大小不能小于镜像/快照大小。从备份创建云硬盘时，size为可选，不指定size时，云硬盘大小和备份大小一致。

snapshot_id 否 String 快照ID，指定该参数表示创建云硬盘方式为从快照创建云硬盘。

volume_type 是 String 云硬盘类型。

目前支持"SATA"，"SAS"，

"GPSSD"和"SSD"四种。

● "SATA"为普通IO云硬盘(已售罄)

● "SAS"为高IO云硬盘

● "GPSSD"为通用型SSD云硬盘

● "SSD"为超高IO云硬盘当指定的云硬盘类型在

avaliability_zone内不存在时，

则创建云硬盘失败。

说明说明：从快照创建云硬盘时，

volume_type字段必须和快照源云硬盘保持一致。了解不同磁盘类型的详细信息，请参见磁盘类型及性能介绍。

枚举值：

● SATA

● SAS

● GPSSD

(33)

参数是否必选参数类型描述 tags 否 Map<String,St

ring> 云硬盘标签信息。

表6-6 CreateVolumeSchedulerHints

dedicated_sto

rage_id 否 String 指定专属存储池ID，表示将云硬

盘创建在该ID对应的存储池中。

响应参数

状态码： 202

表6-7 响应 Body 参数

job_id String 任务ID，云硬盘为按需计费时返回该参数。

说明如果需要查询job的状态，请参考："查询job的状态"。

order_id String 订单ID，云硬盘为包周期计费时返回该参数。

说明

直接在包周期云服务器上新增云硬盘，系统会自动将云硬盘挂载到包周期云服务器上。该情形下也会返回该参数。

● 如果您需要支付订单，请参考："支付包周期产品订单"。

volume_ids Array of

strings 待创建的云硬盘ID列表，在请求体的metadata字段中指定create_for_volume_id为true时才返回该参数。

状态码： 400

error Error object 出现错误时，返回的错误信息

(34)

表6-9 Error

code String 出现错误时，返回的错误码。错误码和其对应的含义请参考错误码说明。

message String 错误提示信息。

请求示例

POST https://{endpoint}/v2.1/{project_id}/cloudvolumes { "volume" : {

"name" : "test_volume_3", "availability_zone" : "az1.dc1", "volume_type" : "SATA", "size" : 120,

"description" : "test", "multiattach" : true, "count" : 1, "tags" : {

"key1" : "value1", "key2" : "value2"

}

}, "bssParam" : {

"chargingMode" : "prePaid", "periodType" : "year", "periodNum" : 1, "isAutoPay" : "true", "isAutoRenew" : "true"

}}

响应示例

状态码： 202 Accepted

● 示例 1

{ "job_id" : "70a599e0-31e7-49b7-b260-868f441e862b", "volume_ids" : [ "e1fa3e72-8c92-4871-9152-bf66fef0afe9" ] }

● 示例 2

{ "order_id" : "CS1711152257C60TL",

"volume_ids" : [ "e1fa3e72-8c92-4871-9152-bf66fef0afe9" ] }

状态码： 400 Bad Request

{ "error" : {

(35)

}}

状态码

状态码描述

202 Accepted 400 Bad Request

错误码

请参见错误码。

6.1.2 创建云硬盘(废弃)

功能介绍

创建一个或多个云硬盘。由于兼容性原因导致存在该接口，目前已经废弃。请使用性能更佳的接口。

调试

URI

POST /v2/{project_id}/cloudvolumes

表6-10 路径参数

project_id 是 String 项目 ID

请求参数

X-Auth-Token 是 String Token的有效期为24小时，需要使用一个Token鉴权时，可以先缓存起来，避免频繁调用。

(36)

volume 是 CreateDiskO

ption object 待创建的云硬盘信息。

表6-13 CreateDiskOption

availability_zo

ne 是 String 指定要创建云硬盘的可用区。

backup_id 否 String 备份ID，从备份创建云硬盘时为必选。

count 否 Integer 批量创云硬盘的个数。如果无该

参数，表明只创建1个云硬盘，

目前最多支持批量创建100个。

从备份创建云硬盘时，不支持批量创建，数量只能为“1”。

如果发送请求时，将参数值设置为小数，则默认取小数点前的整数。

description 否 String 云硬盘的描述。最大支持255个字节。

enterprise_pro

ject_id 否 String 企业项目ID。创建云硬盘时，给

云硬盘绑定企业项目ID。

imageRef 否 String 镜像ID，指定该参数表示创建云

硬盘方式为从镜像创建云硬盘。

(37)

参数是否必选参数类型描述 metadata 否 Map<String,St

ring> 创建云硬盘的metadata信息可选参数如下:metadata中的加密 cmkid字段，与

__system__encrypted配合表示需要加密，cmkid长度固定为36 个字节。

__system__encrypted:

metadata中的表示加密功能的字段,0代表不加密,1代表加密。

不指定该字段时,云硬盘的加密属性与数据源保持一致,如果不是从数据源创建的场景,则默认不加密。

full_clone: 从快照创建云硬盘时，如需使用link克隆方式，请指定该字段的值为0。

hw:passthrough:

● true表示云硬盘的设备类型为SCSI类型，即允许ECS操作系统直接访问底层存储介质。支持SCSI锁命令。

● false表示云硬盘的设备类型为VBD (虚拟块存储设备 , Virtual Block Device)类型，

即为默认类型，VBD只能支持简单的SCSI读写命令。

multiattach 否 Boolean 是否为共享云硬盘。true为共享盘，false为普通云硬盘。

name 否 String 云硬盘名称。如果为创建单个

云硬盘，name为云硬盘名称。

最大支持255个字节。创建的云硬盘数量（count字段对应的值）大于1时，为区分不同云硬盘，创建过程中系统会自动在名称后加“-0000”的类似标记。

例如：volume-0001、

volume-0002。最大支持250个字节。

(38)

shareable 否 String 是否为共享云硬盘。true为共享盘，false为普通云硬盘。该字段已经废弃，请使用

multiattach。

size 是 Integer 云硬盘大小，单位为GB，其限

制如下：系统盘：

1GB-1024GB 数据盘：

10GB-32768GB 创建空白云硬盘和从镜像/快照创建云硬盘时，size为必选，且云硬盘大小不能小于镜像/快照大小。从备份创建云硬盘时，size为可选，不指定size时，云硬盘大小和备份大小一致。

snapshot_id 否 String 快照ID，指定该参数表示创建云硬盘方式为从快照创建云硬盘。

volume_type 是 String 云硬盘类型。

目前支持"SATA"，"SAS"，

"GPSSD"和"SSD"四种。

● "SATA"为普通IO云硬盘(已售罄)

● "SAS"为高IO云硬盘

● "GPSSD"为通用型SSD云硬盘

● "SSD"为超高IO云硬盘当指定的云硬盘类型在

avaliability_zone内不存在时，

则创建云硬盘失败。

说明说明：从快照创建云硬盘时，

volume_type字段必须和快照源云硬盘保持一致。了解不同磁盘类型的详细信息，请参见磁盘类型及性能介绍。

枚举值：

● SATA

● SAS

● GPSSD

● SSD tags 否 Map<String,St

ring> 云硬盘标签信息。

(39)

响应参数

状态码： 202

job_id String 正常返回时返回的任务ID。

说明如果需要查询job的状态，请参考查询job的状态。

状态码： 400

表6-16 Error

请求示例

{ "volume" : { "backup_id" : null, "count" : 1,

"availability_zone" : "az1.dc1", "description" : "test_volume_1", "size" : 120,

"name" : "test_volume_1", "imageRef" : null, "volume_type" : "SSD", "metadata" : {

"__system__encrypted" : "0", "__system__cmkid" : null }

}}

响应示例

(40)

{ "job_id" : "70a599e0-31e7-49b7-b260-868f441e862b"

}

{ "error" : {

"message" : "XXXX", "code" : "XXX"

}}

状态码

状态码描述

错误码

6.1.3 扩容云硬盘

功能介绍

对按需或者包周期云硬盘进行扩容。在扩容包周期云硬盘的场景下：

● 如果您需要查看订单可用的优惠券，请参考"查询订单可用优惠券"。

● 如果您需要支付订单，请参考"支付包周期产品订单"。

● 如果您需要查询订单的资源开通详情，请参考"查询订单的资源开通详情"。

● 如果您需要退订该包周期资源，请参考“退订包周期资源”。

接口约束

● 扩容状态为available的云硬盘时，没有约束限制。

● 扩容状态为in-use的云硬盘时，有以下约束：

– 不支持共享云硬盘，即multiattach参数值必须为false。

– 云硬盘所挂载的云服务器状态必须为ACTIVE、PAUSED、SUSPENDED、

SHUTOFF才支持扩容。

调试

URI

(41)

表6-17 路径参数

项目ID"。

volume_id 是 String 云硬盘ID。

请求参数

bssParam 否 BssParamFor ResizeVolum e object

按需和包周期的扩展参数。

os-extend 是 OsExtend

object 标记扩容云硬盘操作。

(42)

表6-20 BssParamForResizeVolume

isAutoPay 否 String 功能说明：是否立即支付。该参

数只有在云硬盘为包周期的情况下有意义。默认值为false 取值范围：

● true：立即支付，从帐户余额中自动扣费

● false：不立即支付，创建订单暂不支付

缺省值：false 枚举值：

● false

● true

表6-21 OsExtend

new_size 是 Integer 扩容后的云硬盘大小，单位为

GB。扩容的大小必须大于原有云硬盘容量且小于云硬盘最大容量。云硬盘最大容量：

● 数据盘：32768GB

● 系统盘：1024GB

响应参数

状态码： 202

job_id String 任务ID，云硬盘为按需计费时返回该参数。

说明如果需要查询job的状态，请参考："查询job的状态"。

order_id String 订单ID，云硬盘为包周期计费时返回该参数。

说明

● 如果您需要支付订单，请参考："支付包周期产品订单"。

(43)

表6-24 Error

请求示例

POST https://{endpoint}/v2.1/{project_id}/cloudvolumes/{volume_id}/action { "os-extend" : {

"new_size" : 100 }, "bssParam" : { "isAutoPay" : "true"

}}

响应示例

● 示例 1

{ "job_id" : "70a599e0-31e7-49b7-b260-868f441e862b"

}

● 示例 2

{ "order_id" : "CS1711152257C60TL"

}

{ "error" : {

}}

(44)

状态码

状态码描述

错误码

6.1.4 更新云硬盘

功能介绍

更新一个云硬盘的名称和描述。

调试

URI

PUT /v2/{project_id}/cloudvolumes/{volume_id}

表6-25 路径参数

项目ID"。

volume_id 是 String 云硬盘ID。

请求参数

(45)

volume 是 UpdateVolu meOption object

待修改的云硬盘信息

表6-28 UpdateVolumeOption

description 否 String 新的云硬盘的描述，name和 description不能同时为null。最大支持255个字节。

name 否 String 新的云硬盘的名字，name和

description不能同时为null。最大支持255个字节。

响应参数

状态码： 200

attachments Array of Attachment objects

是否挂载信息。

availability_zo

ne String 云硬盘所属AZ。

bootable String 是否为可启动云硬盘。

created_at String 创建云硬盘的时间。

id String 云硬盘ID。

links Array of Link

objects 云硬盘uri自描述信息 metadata VolumeMeta

data object 云硬盘的元数据。

multiattach Boolean 是否为可共享云硬盘。

name String 云硬盘名称

os-vol-host-

attr:host String 预留属性。

(46)

参数参数类型描述 os-vol-tenant-

attr:tenant_id String 云硬盘所属的项目ID。

shareable String 是否为共享云硬盘。

size Integer 云硬盘大小。

snapshot_id String 快照ID。

source_volid String 预留字段。

status String 云硬盘状态。

volume_imag

e_metadata Object 云硬盘镜像的元数据。

说明关于“volume_image_metadata”字段的详细说明，

具体请参见："查询镜像详情"。

volume_type String 云硬盘类型。

description String 云硬盘描述。

os-volume- replication:ext ended_status

String 预留属性。

表6-30 Attachment

attached_at String 挂载的时间信息。

时间格式：UTC YYYY-MM- DDTHH:MM:SS.XXXXXX attachment_i

d String 挂载信息对应的ID。

device String 挂载点。

host_name String 云硬盘挂载到的云服务器对应的物理主机的名称。

id String 挂载的资源ID。

server_id String 云硬盘挂载到的云服务器的 ID。

volume_id String 云硬盘ID。

(47)

表6-31 Link

href String 对应的快捷链接。

rel String 快捷链接标记名称。

表6-32 VolumeMetadata

__system__cm

kid String metadata中的加密cmkid字段，与

__system__encrypted配合表示需要加密，cmkid 长度固定为36个字节。

__system__en

crypted String metadata中的表示加密功能的字段，0代表不加密，1代表加密。不指定该字段时，云硬盘的加密属性与数据源保持一致，如果不是从数据源创建的场景，则默认不加密。

full_clone String 从快照创建云硬盘时的创建方式。

● 0表示使用链接克隆方式。

● 1表示使用全量克隆方式。

hw:passthrou

gh String ● true表示云硬盘的设备类型为SCSI类型，即允许ECS操作系统直接访问底层存储介质。支持 SCSI锁命令。

● false表示云硬盘的设备类型为VBD (虚拟块存储设备 , Virtual Block Device)类型，即为默认类型，VBD只能支持简单的SCSI读写命令。

orderID String metadata中的表示云硬盘计费类型的字段。当该字段有值时，表示该云硬盘的计费类型为包周期计费，否则计费类型为按需计费。

状态码： 400

(48)

表6-34 Error

请求示例

PUT https://{endpoint}/v2/{project_id}/cloudvolumes/{volume_id}

{ "volume" : {

"name" : "test_volume", "description" : "test"

}}

响应示例

状态码： 200 OK

{ "id" : "36ba39af-3579-4e6e-adfc-b764349c0f77", "links" : [ {

"href" : "https://volume.region.xxx.xxx-tsi.de/v2/3cfb09080bd944d0b4cdd72ef26857bd/volumes/

36ba39af-3579-4e6e-adfc-b764349c0f77", "rel" : "self"

}, {

"href" : "https://volume.region.xxx.xxx-tsi.de/3cfb09080bd944d0b4cdd72ef26857bd/volumes/

36ba39af-3579-4e6e-adfc-b764349c0f77", "rel" : "bookmark"

} ],

"name" : "newVolume", "status" : "in-use", "attachments" : [ {

"server_id" : "c3d3250c-7ce5-42cc-b620-dd2b63d19ca5", "attachment_id" : "011a2bdb-a033-4479-845b-50bd8ed7f4d4", "attached_at" : "2017-05-23T11:27:38.604815",

"host_name" : null,

"volume_id" : "36ba39af-3579-4e6e-adfc-b764349c0f77", "device" : "/dev/sdf",

"id" : "36ba39af-3579-4e6e-adfc-b764349c0f77"

} ],

"description" : "new volume", "multiattach" : false, "shareable" : false, "size" : 10, "metadata" : {

"policy" : "dc71a9c9-b3fa-429d-a070-037682d82d21", "attached_mode" : "rw",

"readonly" : "False", "hw:passthrough" : "false"

}, "bootable" : "false",

"availability_zone" : "az-dc-1", "os-vol-host-attr:host" : null, "source_volid" : null,

(49)

"volume_type" : "SATA",

"os-vol-tenant-attr:tenant_id" : null, "volume_image_metadata" : null }

{ "error" : {

}}

状态码

状态码描述

200 OK

400 Bad Request

错误码

6.1.5 扩容云硬盘(废弃)

功能介绍

扩容一个云硬盘扩容状态为available的云硬盘时，没有约束限制。由于兼容性原因导致存在该接口，目前已经废弃。

接口约束

扩容状态为in-use的云硬盘时，有以下约束：不支持共享云硬盘，即multiattach参数值必须为false。云硬盘所挂载的云服务器状态必须为ACTIVE、PAUSED、

SUSPENDED、SHUTOFF才支持扩容。

调试

URI

POST /v2/{project_id}/cloudvolumes/{volume_id}/action

表6-35 路径参数

project_id 是 String 项目ID

(50)

volume_id 是 String 云硬盘ID

请求参数

X-Auth-Token 是 String Token的有效期为24小时，需要使用一个Token鉴权时，可以先缓存起来，避免频繁调用。

os-extend 是 ResizeDiskOp

tion object 标记扩容云硬盘操作

表6-38 ResizeDiskOption

new_size 是 Integer 扩容后的云硬盘大小，单位为

GB。扩容的大小必须大于原有云硬盘容量且小于云硬盘最大容量。云硬盘最大容量：

● 数据盘：32768GB

● 系统盘：1024GB

响应参数

状态码： 200

job_id String 正常返回时返回的任务ID。

说明如果需要查询job的状态，请参考查询job的状态。

(51)

状态码： 400

表6-41 Error

请求示例

{ "os-extend" : { "new_size" : 200 }}

响应示例

状态码： 200 OK

{ "job_id" : "70a599e0-31e7-49b7-b260-868f441e862b"

}

{ "error" : {

}}

状态码

状态码描述

200 OK

400 Bad Request

创建云硬盘_云硬盘 EVS_API参考_API v2_云硬盘_华为云

API 参考

华为技术有限公司

https://www.huawei.com

[email protected]

目 录

1 使用前必读... 1

1.1 概述... 1

1.2 调用说明...1

1.3 终端节点（Endpoint）... 1

1.4 约束与限制... 1

1.5 基本概念...2

1.6 API 版本选择建议... 3

2 API 概览... 4

3 如何调用 API...5

3.1 构造请求...5

3.2 认证鉴权...9

3.3 返回结果... 10

4 快速入门...12

4.1 创建云硬盘... 12

5 API 版本信息查询...14

5.1 查询接口版本信息列表... 14

5.2 查询接口的版本信息... 17

6 API v2... 20

6.1 云硬盘...20

6.1.1 创建云硬盘... 20

6.1.2 创建云硬盘(废弃)... 28

6.1.3 扩容云硬盘... 33

6.1.4 更新云硬盘... 37

6.1.5 扩容云硬盘(废弃)... 42

6.1.6 删除云硬盘... 45

6.1.7 查询所有云硬盘详情... 47

6.1.8 查询所有云硬盘详情(废弃)... 54

6.1.9 查询单个云硬盘详情... 61

6.1.10 查询单个云硬盘详情(废弃)... 67

6.1.11 查询云硬盘列表(废弃)... 73

6.2 云硬盘快照... 76

6.2.1 创建云硬盘快照...77

6.2.2 删除云硬盘快照...80

6.2.3 更新云硬盘快照...82

6.2.4 查询云硬盘快照详细列表信息...85

6.2.5 查询单个云硬盘快照详细信息...90

6.2.6 回滚快照到云硬盘... 93

6.2.7 回滚快照到云硬盘(废弃)... 96

6.3 云硬盘标签... 98

6.3.1 为指定云硬盘批量添加标签... 99

6.3.2 为指定云硬盘批量删除标签...101

6.3.3 获取云硬盘资源的所有标签...103

6.3.4 查询云硬盘标签... 105

6.3.5 通过标签查询云硬盘资源实例详情...108

7 OpenStack Cinder API v2... 117

7.1 云硬盘... 117

7.1.1 创建云硬盘... 117

7.1.2 删除云硬盘... 126

7.1.3 更新云硬盘... 128

7.1.4 添加云硬盘的元数据...133

7.1.5 查询云硬盘类型列表...136

7.1.6 查询云硬盘的单个元数据... 139

7.1.7 查询所有的可用分区信息... 141

7.1.8 查询单个云硬盘类型的详细信息... 143

7.1.9 更新云硬盘的单个元数据... 146

7.1.10 查询云硬盘列表... 149

7.1.11 更新云硬盘的元数据... 153

7.1.12 查询单个云硬盘详情... 156

7.1.13 查询云硬盘的元数据... 161

7.1.14 删除云硬盘的单个元数据...163

7.1.15 查询所有云硬盘详情... 165

7.1.16 查询扩展接口... 171

7.1.17 查询租户的详细配额... 174

7.2 云硬盘 Actions...183

7.2.1 扩容云硬盘... 183

7.2.2 设置云硬盘启动盘标识... 185

7.2.3 设置云硬盘只读标识...188

7.2.4 将云硬盘导出为镜像...190

7.2.5 挂载云硬盘(废弃)...195

7.2.6 卸载云硬盘(废弃)...198

7.2.7 保留云硬盘(废弃)...200

7.2.8 取消保留云硬盘(废弃)... 202

7.3.1 创建云硬盘过户... 204

7.3.2 接受云硬盘过户... 208

目录