在线文档

Document
PD3008 ZStack V3.0.1 开发手册 平台管理

其它文件格式:aid:1516,cn_name: 没有找到文档 PD3008, 请手工处理   电子书  


开发手册

版权声明

版权所有©上海云轴信息科技有限公司 2018。保留一切权利。

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

商标说明

ZStack商标和其他云轴商标均为上海云轴信息科技有限公司的商标。

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

注意

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

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

引言

产品版本

目前与本文档相对应的产品版本为:ZStack 2.3.1

读者对象

本文档详述了ZStack 2.3.1 RESTful API的使用规范,并提供所有API的详细定义。本文档主要适用于以下读者:

  • 架构设计师
  • 开发工程师
  • 测试工程师
  • 项目实施人员
  • 对ZStack有兴趣研究的相关人员

版本更新

2.3.1

2018/04/03主要更新:

  1. 网络拓扑
  2. 新版菜单导航、新版首页
  3. ZWatch:全新监控报警系统
  4. ZStack定制版ISO新增:基于CentOS 7.4深度定制版本
  5. 亲和组
  6. 增强vCenter接管功能:接管vCenter云盘、基于vCenter云路由网络提供网络服务
  7. 一个云主机加载多个ISO
  8. 多种策略创建云主机
  9. 一个二层网络可用于创建多个三层网络
  10. 操作日志/审计全新改版
  11. HTTPS安全访问UI管理界面
  12. 内部访问业务流量的负载均衡
  13. 优化自定义UI
  14. 多个场景新增进度条、操作助手和帮助文档,优化UI交互
  15. 优化部分业务逻辑

2.3.0

2018/02/08主要更新:

  1. 专有网络VPC
  2. 混合云灾备(混合云版支持)
  3. 大屏监控
  4. 用户自定义UI
  5. ImageStore类型镜像服务器支持Ceph类型主存储
  6. 支持vSwitch
  7. 支持vCenter资源同步
  8. ESXi云主机支持扁平网络
  9. 云主机更换操作系统
  10. 跨NFS存储数据迁移
  11. 虚拟IP支持QoS
  12. 支持AD认证
  13. 云主机自定义MAC地址
  14. 强化浏览器上传镜像功能
  15. 新增云盘镜像资源
  16. 数据云盘扩容
  17. 数据云盘规格支持QoS
  18. 停止NeverStop状态的云主机
  19. 开放云路由公网IP,并支持同一虚拟IP多网络服务复用
  20. 支持USB设备透传,强化外接设备透传功能
  21. 增加VDI SPICE流量优化选项
  22. 支持修改已设置的存储网络
  23. 支持设置VXLAN对普通账户的配额
  24. 支持ImageStore类型镜像服务器间的数据同步
  25. 管理节点数据库自动备份到远程服务器
  26. 多个场景新增进度条、操作助手和帮助文档,优化UI交互
  27. 优化部分业务逻辑

2.2

2017/10/16主要更新:

  1. 公有网络创建云主机
  2. 自定义DHCP模式
  3. 新增系统网络
  4. 云主机根云盘扩容
  5. 浏览器添加镜像(目前支持ImageStore类型镜像服务器)
  6. 管理节点高可用:多网络配置
  7. 跨Ceph存储数据迁移
  8. 增强Ceph存储功能
  9. 增强VDI功能
  10. LDAP自定义过滤规则
  11. 增强裸机管理
  12. 单集群支持多类型主存储(目前支持本地存储+NFS/SMP类型)
  13. 更换License支持本地上传
  14. 共享存储指定存储网络,增强云主机高可用
  15. 多个场景新增进度条、操作助手和帮助文档,优化UI交互
  16. 优化部分业务逻辑

2.1

2017/08/14主要更新:

  1. VDI
  2. 裸机管理
  3. GPU透传
  4. 智能报警
  5. 集群挂载多个主存储
  6. 新版定时器
  7. 静态路由
  8. User Data导入
  9. 云路由加载多个公有网络
  10. 增量升级
  11. 优化部分业务逻辑

系列索引

ZStack 2.3.1 开发手册系列索引如下:

  • 《ZStack 2.3.1 开发手册 云资源池》
  • 《ZStack 2.3.1 开发手册 硬件设施》
  • 《ZStack 2.3.1 开发手册 网络资源》
  • 《ZStack 2.3.1 开发手册 网络服务》
  • 《ZStack 2.3.1 开发手册 vCenter》
  • 《ZStack 2.3.1 开发手册 平台运维》
  • 《ZStack 2.3.1 开发手册 平台管理》
  • 《ZStack 2.3.1 开发手册 设置》
  • 《ZStack 2.3.1 开发手册 系统全局相关》
  • 《ZStack 2.3.1 开发手册 混合云》

API规范概述

ZStack 2.3.1提供原生RESTful支持。您可以通过REST定义的架构设计原则和约束条件,并使用支持HTTP的编程语言进行开发。

HTTP方法 (HTTP Verbs)

当前API支持如下操作资源的方法:

|方法名|描述| |---|--| |GET| 获取资源信息。

  • 所有的查询API以及读API均使用该方法。

    | |POST| 创建一个资源。

    | |PUT|修改一个资源。- 所有对资源的修改操作,以及类RPC调用的操作,例如启动虚拟机,均使用该方法。

| |DELETE|删除一个资源。|

Parent topic: API规范概述

传参方式

URL、Query String、HTTP body三种方式均可用于传参。每种方式可以单独使用,也可以混合使用,具体使用哪种传参方式由具体API决定。

URL传参

当对某具体资源进行操作时,资源的UUID通过编码到URL的方式进行传参。

例如启动一个UUID为 f97143d60f1042c9badd9a1336d3c105的虚拟机,URL格式为:

zstack/v1/vm-instances/f97143d60f1042c9badd9a1336d3c105/actions

这里UUID编码到URL路径当中。

Query String传参

所有使用HTTP GET方法的API均使用Query String传参。

例如查询所有状态为Running的虚拟机, URL格式为:

zstack/v1/vm-instances?condition=state=Running

HTTP Body传参

当使用POST方法创建一个资源,或PUT方法修改一个资源时,除通过URL传参的部分外,剩余参数均通过HTTP Body传参。

例如在指定物理机上启动一个虚拟机:

``` PUT zstack/v1/vm-instances/f97143d60f1042c9badd9a1336d3c105/actions

{ "startVmInstance": { "hostUuid": "8aef7e3a53b34eedaa05027a919156d9" } } ```

这里虚拟机的UUID通过URL传参,参数hostUuid则通过HTTP Body传递。

Parent topic: API规范概述

HTTP Headers

当前API使用如下自定义HTTP Headers:

Authorization

除了少数API外(例如登录API),使用ZStack API前都需要一个会话(session),在调用API时通过Authorization HTTP Header传递会话UUID。该Header的格式为:

Authorization: OAuth 会话UUID

举例:

Authorization: OAuth 34cbfddd470a47d8bdb0727cd2182618

Note: OAuth和会话UUID之间用空格分隔。

X-Job-UUID

对于异步API,可以通过X-Job-UUID HTTP Header来指定该API Job的UUID,例如:

X-Job-UUID: d825b1a26f4e474b8c59306081920ff2

如果未指定该HTTP Header,ZStack会自动为API Job生成一个UUID。

Note:

X-Job-UUID必须为一个v4版本的UUID(即随机UUID)字符串去掉连接符-。ZStack会验证X-Job-UUID格式的合法性,并对非法的字符串返回一个400 Bad Request的错误。

X-Web-Hook

对于异步API,可以通过X-Web-Hook HTTP Header指定一个回调URL用于接收API 返回。通过使用回调URL的方法,调用者可以避免使用轮询去查询一个异步API的执行结果。举例:

X-Web-Hook: http://localhost:5000/api-callback

X-Job-Success

当使用了X-Web-Hook回调的方式获取异步API结果时,ZStack推送给回调URL的HTTP Post请求中会包含X-Job-Success HTTP Header指明该异步API的执行结果是成功还是失败。例如:

X-Job-Success: true

当值为true时执行成功,为false时执行失败。

Parent topic: API规范概述

HTTP返回码 (HTTP Status Code)

ZStack使用如下返回码:

|返回码|意义| |---|--| |200|API执行成功。| |202|API请求已被ZStack接受,用户需要通过轮询或Web Hook的方式获取API结果。该返回码只在调用异步API时出现。| |400|API请求未包含必要的参数或包含了非法的参数。具体信息可以从HTTP Response Body获得。| |404|URL不存在,通常是指定了错误的API URL。如果访问的URL是异步API返回的轮询地址,表示该轮询地址已经过期。| |405|API调用使用了错误的HTTP方法,例如在创建一个资源的时候用了GET方法而不是POST方法。| |500| ZStack RESTful终端遭遇了一个内部错误。| |503|API所执行的操作引发了一个错误,例如资源不足无法创建虚拟机。错误的具体信息可以从HTTP Response Body。|

Parent topic: API规范概述

API种类

ZStack的API分为同步API和异步API两种:

同步API

所有使用GET方法的API都是同步API,调用方收到的HTTP Response中直接包含了API的结果。例如:

``` GET zstack/v1/zones/f3fa7671894a40f6a73f5bfc7d90c126

{ "inventory": { "uuid": "f3fa7671894a40f6a73f5bfc7d90c126", "name": "zone1", "description": "test", "state": "Enabled", "type": "zstack", "createDate": "Jan 6, 2017 3:51:16 AM", "lastOpDate": "Jan 6, 2017 3:51:16 AM" } } ```

异步API

除了登录相关的API外,所有不使用GET方法的API都为异步API。用户调用一个异步API成功后会收到202返回码以及 Body中包含的一个轮询地址(location字段),用户需要周期性的GET该轮询地址以获得API的执行结果。例如:

``` Status Code: 202

Body:

{ "location": "http://localhost:8989/v1/api-jobs/967a26b7431c49c0b1d50d709ef1aef3" } ```

通常情况下GET一个轮询地址可以得到四种返回:

  1. 202返回码表示该API仍在处理中,用户需要继续轮询。
  2. 200返回码表示API执行成功,Body中包含API结果。
  3. 503返回码表示API执行失败,Body中包含错误码。
  4. 404返回码,则表示轮询地址已经过期,产生这种结果的原因可能是用户访问了一个错误的轮询地址,或者太久没有访问该轮询地址(例如超过2天没有访问),该轮询地址已经被删除。

异步API也可以用Web Hook的方式获得结果,具体方法见后面章节。

Parent topic: API规范概述

API操作

跟所有的RESTful API类似,绝大多数ZStack API执行的是CRUD(Create, Read, Update, Delete)操作,以及类RPC操作。

创建资源

所有资源的创建都使用POST方法,参数通过HTTP Body传递,例如创建一个虚拟机:

``` POST zstack/v1/vm-instances

Authorization: OAuth 0c234e29a2ad4ff4b0d97d4f3b47c6cf

{ "params": { "l3NetworkUuids": ["37a701c7fe4a40758da15593aedd8aff"], "defaultL3NetworkUuid": "37a701c7fe4a40758da15593aedd8aff", "dataDiskOfferingUuids": [], "name": "TestVm", "description": "Test", "systemTags": [], "instanceOfferingUuid": "dd53f94b58924510b0122e40799a4114", "type": "UserVm", "imageUuid": "cc7b56780879409f98c1f992b75a12b0" } } ```

查询资源

资源的查询使用GET方法,查询条件通过Query String传参,例如查询集群cluster1中名字不等于 web-vm的虚拟机:

``` GET zstack/v1/vm-instances?condition=name!=web-vm&condition=cluster.name=cluster1

Authorization: OAuth 0c234e29a2ad4ff4b0d97d4f3b47c6cf ```

如果已知资源的UUID,要直接获取该资源的信息,直接使用GET方法不加任何查询条件,例如:

``` GET zstack/v1/vm-instances/56f0fd314a2647ffb4f9565f6d05858e

Authorization: OAuth 0c234e29a2ad4ff4b0d97d4f3b47c6cf ```

返回UUID为56f0fd314a2647ffb4f9565f6d05858e虚拟机的信息。

删除资源

删除资源使用DELETE方法,被删除资源的UUID编码在URL中,例如:

``` DELETE zstack/v1/vm-instances/56f0fd314a2647ffb4f9565f6d05858e

Authorization: OAuth 0c234e29a2ad4ff4b0d97d4f3b47c6cf ```

删除UUID为56f0fd314a2647ffb4f9565f6d05858e的虚拟机。

修改资源与类RPC操作

但由于IaaS本身业务的性质,一部分操作更类似于RPC(远程调用)而非CRUD操作,例如启动虚拟机。根据RESTful API的一些最佳实践,ZStack将这些操作都归为资源的actions子资源,例如启动虚拟机、 停止虚拟机都是对虚拟机的actions子资源进行操作。举个例子:

启动虚拟机:

``` PUT zstack/v1/vm-instances/d46841bd4ebd47f8bf0bed85c3bdf0db/actions

{ "startVmInstance": {} } ```

停止虚拟机:

``` PUT zstack/v1/vm-instances/d46841bd4ebd47f8bf0bed85c3bdf0db/actions

{ "stopVmInstance": {} } ```

在上面的例子中,两个操作都访问的是相同的URL/v1/vminstances/d46841bd4ebd47f8bf0bed85c3bdf0db/actions, 具体的操作类型由包含在Body中的字段名表示,例如stopVmInstance,如果该API包含额外参数,则包含在操作字段名对应的map中。

资源操作的具体字段名和例子参考每个API的详细文档。

Parent topic: API规范概述

基本流程示例

在下例中,我们会创建一个Zone,以展示API使用的基本流程:

登录

使用API的第一步是登录以获取一个Session UUID,以供后续API调用使用。

``` PUT zstack/v1/accounts/login

body:

{ "logInByAccount": { "password": "b109f3bbbc244eb82441917ed06d618b9008dd09b3befd1b5e07394c706a8bb980b1d7785e5976ec049b46df5f1326af5a2ea6d103fd07c95385ffab0cacbc86", "accountName": "admin" } } ```

这里的密码是用sha512哈希后的结果。

API返回如下:

``` status code: 200

body:

{ "inventory": { "uuid": "00d038b699b74e76a01705918d48d939", "accountUuid": "36c27e8ff05c4780bf6d2fa65700f22e", "userUuid": "36c27e8ff05c4780bf6d2fa65700f22e", "expiredDate": "Jan 1, 2017 11:31:06 AM", "createDate": "Jan 1, 2017 9:31:06 AM" } } ```

返回内容中包含账户UUID等其他字段,我们需要的session UUID包含在字段uuid中:00d038b699b74e76a01705918d48d939

创建Zone

``` POST zstack/v1/zones

headers:

Authorization: OAuth 00d038b699b74e76a01705918d48d939

body:

{ "params": { "name": "Zone1", "description": "Test" } } ```

由于创建Zone操作是一个异步API,API返回不是直接的结果,而是一个轮询地址:

``` status code: 202

body:

{ "location": "http://localhost:8989/v1/api-jobs/d0345d3ddcae485f8170572b15a2b581" } ```

用户需要周期性的轮询API结果:

``` GET http://localhost:8989/v1/api-jobs/d0345d3ddcae485f8170572b15a2b581

Authorization: OAuth 00d038b699b74e76a01705918d48d939 ```

如果API还未执行完成,上述GET操作得到的仍然是202返回码和上述轮询地址。当操作完成时,得到的结果如下:

``` status code: 200

body:

{ "inventory": { "uuid": "f52fe55b64094ceb99b3893a238c4931", "name": "Zone1", "description": "Test", "state": "Enabled", "type": "zstack", "createDate": "Jan 1, 2017 9:31:07 AM", "lastOpDate": "Jan 1, 2017 9:31:07 AM" } } ```

查询Zone

要获取创建的Zone的信息,可以用GET查询:

``` GET zstack/v1/zones/f52fe55b64094ceb99b3893a238c4931

Authorization: OAuth 00d038b699b74e76a01705918d48d939 ```

返回:

``` status code: 200

body:

{ "inventory": { "uuid": "f52fe55b64094ceb99b3893a238c4931", "name": "Zone1", "description": "Test", "state": "Enabled", "type": "zstack", "createDate": "Jan 1, 2017 9:31:07 AM", "lastOpDate": "Jan 1, 2017 9:31:07 AM" } } ```

登出

当所有API调用完毕,我们需要对已登录的session进行登出操作:

DELETE zstack/v1/accounts/sessions/00d038b699b74e76a01705918d48d939

返回

status code: 200

Parent topic: API规范概述

Webhook

对于异步API使用轮询的方式查询操作结果是一种低效的方式,为此ZStack提供Webhook的方式主动推送异步API结果给调用者。

要使用Webhook功能,调用者只需在HTTP Headers中指定X-Job-UUID和X-Web-Hook即可。以上面创建Zone为例,使用Webhook的API版本为:

``` POST zstack/v1/zones

headers:

Authorization: OAuth 00d038b699b74e76a01705918d48d939 X-Job-UUID: d0345d3ddcae485f8170572b15a2b581 X-Web-Hook: http://127.0.0.1:8989/rest-webhook

body:

{ "params": { "name": "Zone1", "description": "Test" } } ```

API返回仍然是202返回码和一个轮询地址,但调用者无需再轮询。API执行成功后,结果会被推送到

http://127.0.0.1:8989/rest-webhook

``` POST http://127.0.0.1:8989/rest-webhook

headers:

X-Job-Success: true X-Job-UUID: d0345d3ddcae485f8170572b15a2b581

body:

{ "inventory": { "uuid": "f52fe55b64094ceb99b3893a238c4931", "name": "Zone1", "description": "Test", "state": "Enabled", "type": "zstack", "createDate": "Jan 1, 2017 9:31:07 AM", "lastOpDate": "Jan 1, 2017 9:31:07 AM" } } ```

推送的结果之中,X-Job-Success指明了API执行成功与否,X-Job-UUID包含值跟API调用时的X-Job-UUID相同,调用者可以对应结果和API。

Parent topic: API规范概述

查询API

用户可以用GET方法对一个资源进行查询,并且可以像MySQL一样指定多个查询条件、排序方式、选择字段、以及进行跨表查询等等。

支持超过400万个单项查询条件,以及400万阶乘的组合查询条件。

单表查询

例如:

GET zstack/v1/vm-instances?q=name=vm1

查询名字为vm1的虚拟机。

例如:

GET zstack/v1/vm-instances?q=name=vm1&q=state=Running

查询名字为vm1并且状态为Running的虚拟机。

这两个例子都是对虚拟机资源本身查询,反应到数据库层面还属于单表查询。

跨表查询

我们可以通过.进行跨表查询。

例如:

GET zstack/v1/vm-instances?q=vmNics.ip=192.168.10.100

查询IP地址为192.168.10.100的虚拟机,这里对虚拟机和网卡两张表进行了跨表查询。

例如:

GET zstack/v1/vm-instances?q=host.managementIp=10.10.20.3

查询IP为10.10.20.3上运行的所有虚拟机。这里对虚拟机和物理机两张表进行了跨表查询。

所有资源的查询API都支持下列参数

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |q (可选)|List|query|见查询条件。省略该字段将返回所有记录,返回记录数的上限受限于limit字段| |0.6| |limit (可选)|Integer|query|最多返回的记录数,类似MySQL的limit,默认值1000| |0.6| |start (可选)|Integer|query|起始查询记录位置,类似MySQL的offset。跟limit配合使用可以实现分页| |0.6| |count (可选)|Boolean|query|计数查询,相当于MySQL中的count()函数。当设置成true时,API只返回的是满足查询条件的记录数| |0.6| |groupBy (可选)|String|query|以字段分组,相当于MySQL中的group by关键字。例如groupBy=type| |1.9| |replyWithCount (可选)|Boolean|query|见分页查询| |0.6| |sort (可选)|String|query|以字段排序,等同于MySQL中的sort by关键字,例如sort=+ip。必须跟+或者-配合使用,+表示升序,-表示降序,后面跟排序字段名|`+`字段名,`-`字段名|0.6| |sortDirection (可选)|String|query|字段排序方向,必须跟sortBy配合使用|ascdesc|0.6| |fields (可选)|List|query|指定返回的字段,等同于MySQL中的select字段功能。例如fields=name,uuid,则只返回满足条件记录的name和uuid字段| |0.6|

查询条件

的查询条件类似于MySQL数据库。

例如:

uuid=bfa67f956afb430890aa49db14b85153 totalCapacity>2000 vmInstanceUuid not null

Note:

  • 字段名、查询操作符、匹配值三者之间不能有任何空格
  • 例如uuid = 25506342d1384c07b7342373a57475b9就是一个错误的查询条件,必须写为uuid=25506342d1384c07b7342373a57475b9

多个查询条件之间是关系。总共支持10个查询操作符:

  1. =: 等于,例如:

    vmInstanceUuid=c4981689088b40f98d2ade2548c323da

  2. !=: 不等于,例如:

    vmInstanceUuid!=c4981689088b40f98d2ade2548c323da

  3. >: 大于

  4. <: 小于
  5. >=: 大于等于
  6. <=: 小于等于
  7. ?=: in操作符,测试字段值是否在一个集合。集合中的值以,分隔。例如测试uuid是否属于某个集合:

    uuid?=25506342d1384c07b7342373a57475b9,bc58d68090ac42358c0cb0fe72e3287f

  8. !?=: not int操作符,测试字段值是否不属于一个集合。集合中的值以,分隔,例如测试name是否不等于VM1和VM2:

    name!?=VM1,VM2

  9. ~=: 字符串模糊匹配,相当于MySQL中的like操作。使用%匹配一个或多个字符,使用_匹配一个字符。 例如查询一个名字是以IntelCore开头的:

    name~=IntelCore%

  10. 或者查询一个名字是以IntelCore开头,以7结尾,中间模糊匹配一个字符:

    name~=IntelCore_7

    这样名字是IntelCoreI7IntelCoreM7的记录都会匹配上。

  11. !~=: 模糊匹配非操作。查询一个字段不能模糊匹配到某个字符串,匹配条件与~=相同。

  12. is null: 字段为null:

    name is null

  13. not null: 字段不为null:

    name not null

分页查询

startlimitreplyWithCount三个字段可以配合使用实现分页查询。

  • start指定起始查询位置。
  • limit指定查询返回的最大记录数。
  • replyWithCount被设置成true后,查询返回中会包含满足查询条件的记录总数,跟start值比较就可以得知还需几次分页。

例如:

总共有1000记录满足查询条件,使用如下组合:

start=0 limit=100 replyWithCount=true

则API返回将包含头100条记录,以及total字段等于1000,表示总共满足条件的记录为1000。

获取资源可查询字段

由于支持的查询条件数非常巨大,我们无法在文档中枚举所有的查询条件。

用户可以使用命令行工具-cli的自动补全功能来查看一个资源可查询的字段以及可跨表查询的字段。

  • 以查询虚拟机为例,在-cli里输入QueryVmInstance并按Tab键补全,可以看到提示页面:

    ```

    • >>>QueryVmInstance [Query Conditions:] allVolumes. cluster. host. image. instanceOffering. rootVolume. vmNics. zone.

    systemTag= userTag= allocatorStrategy= clusterUuid= cpuNum= cpuSpeed= createDate= defaultL3NetworkUuid= description= groupBy= hostUuid= hypervisorType= imageUuid= instanceOfferingUuid= lastHostUuid= lastOpDate= memorySize= name= platform= rootVolumeUuid= state= type= uuid= zoneUuid=

    [Parameters:] count= fields= limit= replyWithCount= sortBy= sortDirection= start= timeout=
    ```

  • 这里中间行:

    __systemTag__= __userTag__= allocatorStrategy= clusterUuid= cpuNum= cpuSpeed= createDate= defaultL3NetworkUuid= description= groupBy= hostUuid= hypervisorType= imageUuid= instanceOfferingUuid= lastHostUuid= lastOpDate= memorySize= name= platform= rootVolumeUuid= state= type= uuid= zoneUuid=

    __systemTag____userTag__两个特殊查询条件外,其余均为虚拟机表的原生字段,用户可以在API的查询条件里面指定它们,并且可以在fields参数中指定这些字段来过滤其它不希望API返回的字段。

    例如:

    GET zstack/v1/vm-instances?q=cpuNum>5

    返回CPU数量多于5的虚拟机。

    GET zstack/v1/vm-instances?q=hypervisorType=KVM&fields=uuid&fields=name

    返回虚拟化类型为KVM的虚拟机,由于在fields指定了uuid和name两个字段,API返回中只会包含虚拟机的name和uuid。

    Note:

    只有资源的原生字段可以被fields选取,__userTag____systemTag__以及下面讲到的跨表字段均不能出现在fields参数中。

  • 提示的第一行:

    ```

    allVolumes. cluster. host. image. instanceOffering. rootVolume. vmNics. zone. ```

    指明了虚拟机资源可以跟哪些资源做跨表查询,例如:allVolumes代表云盘,cluster代表集群,vmNics代表网卡等。

    如需查看这些资源的具体字段,只需输入资源名加.号,并按Tab键补全。

    例如:

    ```

    • >>>QueryVmInstance vmNics. [Query Conditions:] vmNics.eip. vmNics.l3Network. vmNics.loadBalancerListener. vmNics.portForwarding. vmNics.securityGroup. vmNics.vmInstance.

    vmNics.systemTag= vmNics.userTag= vmNics.createDate= vmNics.deviceId= vmNics.gateway= vmNics.ip= vmNics.l3NetworkUuid= vmNics.lastOpDate= vmNics.mac= vmNics.metaData= vmNics.netmask= vmNics.uuid= vmNics.vmInstanceUuid=
    ```

    这里我们输入了资源vmNics并用.号表示我们要做一个跨表查询,Tab键为我们补全了vmNics资源的原生字段以及可跨表查询的其它资源。

    • 例如vmNics.ip表示网卡的原生字段ip

GET zstack/v1/vm-instances?q=vmNics.ip=192.168.0.100

    进行了一个跨表查询,条件是网卡表的**ip**字段,返回的结果是**ip**为*192.168.0.100*的虚拟机。  -   网卡资源同样可以跟其它资源进行跨表查询,例如**vmNics.eip**。      将网卡表和EIP表进行跨表:      ```     GET zstack/v1/vm-instances?q=vmNics.eip.ip=192.168.0.100     ```      进行了跨3表查询,返回的是EIP为*192.168.0.100*的虚拟机。 
  • 通过资源间连续跨表,一个资源几乎跟系统中多个有逻辑关系的资源进行跨表,例如:

    ```

    • >>>QueryVmInstance zone.cluster.l2Network.l3Network. [Query Conditions:] zone.cluster.l2Network.l3Network.ipRanges. zone.cluster.l2Network.l3Network.l2Network. zone.cluster.l2Network.l3Network.networkServices. zone.cluster.l2Network.l3Network.serviceProvider. zone.cluster.l2Network.l3Network.vmNic. zone.cluster.l2Network.l3Network.zone.

    zone.cluster.l2Network.l3Network.systemTag= zone.cluster.l2Network.l3Network.userTag= zone.cluster.l2Network.l3Network.createDate= zone.cluster.l2Network.l3Network.description= zone.cluster.l2Network.l3Network.dnsDomain= zone.cluster.l2Network.l3Network.l2NetworkUuid= zone.cluster.l2Network.l3Network.lastOpDate= zone.cluster.l2Network.l3Network.name= zone.cluster.l2Network.l3Network.state= zone.cluster.l2Network.l3Network.system= zone.cluster.l2Network.l3Network.type= zone.cluster.l2Network.l3Network.uuid= zone.cluster.l2Network.l3Network.zoneUuid= ```

    分别跟zone, cluster, l2Network, l3Network多个资源进行跨表。

    Note:

    • 由于一个资源的逻辑关系存在环路,例如以虚拟机为主体可以跟网卡进行跨表,例如QueryVmInstance vmNics.,同时以网卡为查询主体也可以跟虚拟机进行跨表QueryVmNic vmInstance.,这样就会存在环路路径。
    • 例如 QueryVmInstance vmNics.vmInstance.name=vm1通过跨表查询了name=vm1的虚拟机,它的实际效果跟QueryVmInstance name=vm1完全等同。这里的跨表是无意义的,只会生产复杂的SQL语句导致低效的数据库查询。在使用中应该避免这种环路跨表查询。
  • __systemTag____userTag__是两个特殊的查询条件,允许用户通过tag查询资源。

    例如:

    QueryVmInstance __systemTag__=staticIp:10.10.1.20

    查询具有staticIp:10.10.1.20这个tag的虚拟机。

Parent topic: API规范概述

用户管理相关接口

创建账户(CreateAccount)

API请求

URLs

POST zstack/v1/accounts

Headers

Authorization: OAuth the-session-uuid

Body

{ "params": { "name": "test", "password": "password" }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X POST -d '{"params":{"name":"test","password":"password"}}' \ http://localhost:8080/zstack/v1/accounts

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |name|String|body(包含在params结构中)|资源名称| |0.6| |password|String|body(包含在params结构中)|密码| |0.6| |type (可选)|String|body(包含在params结构中)|账户类型| - System - Admin - Normal

|0.6| |description (可选)|String|body(包含在params结构中)|资源的详细描述| |0.6| |resourceUuid (可选)|String|body(包含在params结构中)|资源UUID| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "uuid": "3f7b4eeaeba1491cb0493753dd6ce102", "name": "test", "type": "Normal" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventory|AccountInventory|详情参考inventory|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |name|String|资源名称|0.6| |description|String|资源的详细描述|0.6| |type|String|账户类型(管理员,普通账户)|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

CreateAccountAction action = new CreateAccountAction(); action.name = "test"; action.password = "password"; action.sessionId = "b99c5c5c60864e339771c582ac7b64e7"; CreateAccountAction.Result res = action.call();

Python SDK

CreateAccountAction action = CreateAccountAction() action.name = "test" action.password = "password" action.sessionId = "8f5e798859344f93994fe0a58e000b27" CreateAccountAction.Result res = action.call()

Parent topic: 用户管理相关接口

删除账户(DeleteAccount)

API请求

URLs

DELETE zstack/v1/accounts/{uuid}

Headers

Authorization: OAuth the-session-uuid

Body

{ "params": { "deleteMode": "Permissive" }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth cd1c2bf992d340f8bcec91c61b0ca826" \ -X DELETE http://localhost:8080/zstack/v1/accounts/a58b85e7b9804a56b09fd538107a945f

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid|String|url|资源的UUID,唯一标示该资源| |0.6| |deleteMode (可选)|String|body(包含在params结构中)|删除模式| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

DeleteAccountAction action = new DeleteAccountAction(); action.uuid = "241212c7ec464e468e3a6814b256253f"; action.deleteMode = "Permissive"; action.sessionId = "23751519f2bc4723a80fec55425160d2"; DeleteAccountAction.Result res = action.call();

Python SDK

DeleteAccountAction action = DeleteAccountAction() action.uuid = "8c848dc5f8ff4daab75d29f1eb41edc2" action.deleteMode = "Permissive" action.sessionId = "60312ff3c895453ebac617cf6f38af97" DeleteAccountAction.Result res = action.call()

Parent topic: 用户管理相关接口

查询账户(QueryAccount)

API请求

URLs

GET zstack/v1/accounts GET zstack/v1/accounts/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth c2184a4f89a344818de241e4af916fbf" \ -X GET http://localhost:8080/zstack/v1/accounts?q=name=test

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 7b85ed5d64a34ce6b87b923522739135" \ -X GET http://localhost:8080/zstack/v1/accounts/ac726222a7d047a481ef54cde4f519b5

可查询字段

运行zstack-cli命令行工具,输入QueryAccount并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例

{ "inventories": [ { "uuid": "c5962adc77ff40d980bcfe68a39b6fc5", "name": "test", "type": "Normal" } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventories|List|详情参考inventories|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventories

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |name|String|资源名称|0.6| |description|String|资源的详细描述|0.6| |type|String|账户类型(管理员,普通账户)|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

QueryAccountAction action = new QueryAccountAction(); action.conditions = asList("name=test"); action.sessionId = "19d580ead5c74d768b0ca1fdafa476d4"; QueryAccountAction.Result res = action.call();

Python SDK

QueryAccountAction action = QueryAccountAction() action.conditions = ["name=test"] action.sessionId = "d29206d889c94715b331dac2ad12376a" QueryAccountAction.Result res = action.call()

Parent topic: 用户管理相关接口

更新账户(UpdateAccount)

API请求

URLs

PUT zstack/v1/accounts/{uuid}

Headers

Authorization: OAuth the-session-uuid

Body

{ "updateAccount": { "password": "updatepassword", "name": "updatename" }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X PUT -d '{"updateAccount":{"password":"updatepassword","name":"updatename"}}' \ http://localhost:8080/zstack/v1/accounts/99fcb2ad540c36f09e87c820ac6cb4cb

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid|String|url|资源的UUID,唯一标示该资源| |0.6| |password (可选)|String|body(包含在updateAccount结构中)|密码| |0.6| |name (可选)|String|body(包含在updateAccount结构中)|账户名称| |0.6| |description (可选)|String|body(包含在updateAccount结构中)|资源的详细描述| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "uuid": "dda8acd917444887b267d1beb53332d6", "name": "test", "type": "Normal" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventory|AccountInventory|详情参考inventory|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |name|String|资源名称|0.6| |description|String|资源的详细描述|0.6| |type|String|账户类型(管理员,普通账户)|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

UpdateAccountAction action = new UpdateAccountAction(); action.uuid = "a0895597ee22409099fa936047203424"; action.password = "updatepassword"; action.name = "updatename"; action.sessionId = "1fafdbb72ee04075afcaa40ed3584016"; UpdateAccountAction.Result res = action.call();

Python SDK

UpdateAccountAction action = UpdateAccountAction() action.uuid = "8362ff8c83644c4d84148d57a6a129ae" action.password = "updatepassword" action.name = "updatename" action.sessionId = "a654692862be4bf8b8226f809ed87eed" UpdateAccountAction.Result res = action.call()

Parent topic: 用户管理相关接口

使用账户身份登录(LogInByAccount)

API请求

URLs

PUT zstack/v1/accounts/login

Body

{ "logInByAccount": { "accountName": "test", "password": "password" }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -X PUT -d '{"logInByAccount":{"accountName":"test","password":"password"}}' \ http://localhost:8080/zstack/v1/accounts/login

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |accountName|String|body(包含在logInByAccount结构中)|账户名称Note: 账户名称和账户UUID不能同时为空

| |0.6| |password|String|body(包含在logInByAccount结构中)|密码| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "uuid": "622242fe0c58477286b67695210af4d6", "accountUuid": "b49f63f8b86d4f19b65d0f0dc756e063", "expiredDate": "Apr 24, 2017 7:11:05 PM" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventory|SessionInventory|详情参考inventory|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |accountUuid|String|账户UUID|0.6| |userUuid|String|用户UUIDNote: 账户名称和账户UUID不能同时为空

|0.6| |expiredDate|Timestamp|会话过期日期|0.6| |createDate|Timestamp|创建时间|0.6|

SDK示例

Java SDK

LogInByAccountAction action = new LogInByAccountAction(); action.accountName = "test"; action.password = "password"; LogInByAccountAction.Result res = action.call();

Python SDK

LogInByAccountAction action = LogInByAccountAction() action.accountName = "test" action.password = "password" LogInByAccountAction.Result res = action.call()

Parent topic: 用户管理相关接口

获取账户配额使用情况(GetAccountQuotaUsage)

API请求

URLs

GET zstack/v1/accounts/quota/{uuid}/usages

Headers

Authorization: OAuth the-session-uuid

Body

{ "params": {}, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth f1ec41a9dad54fdcbeb096ba7d7ec347" \ -X GET http://localhost:8080/zstack/v1/accounts/quota/5d73926d39d84ddfbcecb28fb3e64198/usages

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid|String|url|资源的UUID,唯一标示该资源| |0.6| |systemTags (可选)|List|query|系统标签| |0.6| |userTags (可选)|List|query|用户标签| |0.6|

API返回

返回示例

{ "usages": [ { "name": "testquota", "total": 20.0, "used": 10.0 } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |usages|List|详情参考usages|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#usages

|名字|类型|描述|起始版本| |--|--|--|----| |name|String|资源名称|0.6| |total|Long|配额总量|0.6| |used|Long|配额已用量|0.6|

SDK示例

Java SDK

GetAccountQuotaUsageAction action = new GetAccountQuotaUsageAction(); action.uuid = "a4b28114528645989d70729385149220"; action.sessionId = "0e8ef3f8ed9145d3a6c81cc960d6e23d"; GetAccountQuotaUsageAction.Result res = action.call();

Python SDK

GetAccountQuotaUsageAction action = GetAccountQuotaUsageAction() action.uuid = "9059f618b9f94b62a55da7b0f21cc66e" action.sessionId = "26a155d4bb6b4fbaaddc48406afbed2b" GetAccountQuotaUsageAction.Result res = action.call()

Parent topic: 用户管理相关接口

查询账户资源引用(QueryAccountResourceRef)

API请求

URLs

GET zstack/v1/accounts/resources/refs

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 7ab81289ce1747e9b0087190338f19b5" \ -X GET http://localhost:8080/zstack/v1/accounts/resources/refs?q=acountUuid=36f13d04700e489ea4ef8887fe233136

可查询字段

运行zstack-cli命令行工具,输入QueryAccountResourceRef并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例

{ "inventories": [ { "id": 1.0, "accountUuid": "a27e124c2a8441be8212a622848c28cd", "ownerAccountUuid": "b22d5d9b1c084589aa1abe30d2783bb8", "resourceUuid": "c2fa286ab4ac41f18ce5219cc4482641", "resourceType": "ImageVO", "permission": 1.0, "isShared": false } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventories|List|详情参考inventories|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventories

|名字|类型|描述|起始版本| |--|--|--|----| |accountUuid|String|账户UUID|0.6| |resourceUuid|String|资源UUID|0.6| |resourceType|String|资源类型|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

QueryAccountResourceRefAction action = new QueryAccountResourceRefAction(); action.conditions = asList("acountUuid=184ad43718eb4731b62d216745e0e097"); action.sessionId = "87bbd9779dbf4db0bfa73fbc9f073bec"; QueryAccountResourceRefAction.Result res = action.call();

Python SDK

QueryAccountResourceRefAction action = QueryAccountResourceRefAction() action.conditions = ["acountUuid=82d42d0824be43688f0769c11b0aab6e"] action.sessionId = "69a28a3c4cce4dfca45905226a3ca1c8" QueryAccountResourceRefAction.Result res = action.call()

Parent topic: 用户管理相关接口

共享资源给账户(ShareResource)

API请求

URLs

PUT zstack/v1/accounts/resources/actions

Headers

Authorization: OAuth the-session-uuid

Body

{ "shareResource": { "resourceUuids": [ "62113cf71892442daf57fe1a21606e7b", "e8d14f0a61d7497c83cf9451bdd392a3" ], "accountUuids": [ "17c6a138e5f04df4ad8938fa8bd06340", "7063dc465e7c42739fdb5fd7d3e373f4" ], "toPublic": false }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X PUT -d '{"shareResource":{"resourceUuids":["05c5cdd1a5693e53ad3212a69b808883","49c6493b8eaf3765806aeb17071e779f"],"accountUuids":["62c084e3a2053b089b8b95fe452856e7","194f8c7d98963e628b9967b0df7eecae"],"toPublic":false}}' \ http://localhost:8080/zstack/v1/accounts/resources/actions

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |resourceUuids|List|body(包含在shareResource结构中)|资源UUID列表| |0.6| |accountUuids (可选)|List|body(包含在shareResource结构中)|账户UUID列表| |0.6| |toPublic (可选)|boolean|body(包含在shareResource结构中)|全局共享Note: toPublic参数被设为false时,账户uuid不能为空

| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

ShareResourceAction action = new ShareResourceAction(); action.resourceUuids = asList("91081232bea84a50af90c7da27d54442","91d6ee72dbd246a88f3004cbaac20998"); action.accountUuids = asList("b3dcbb40827441b5aef2fd3150baa3a9","3985fbda90044fcc8e45d1fbe002eec4"); action.toPublic = false; action.sessionId = "43b022aa93aa4e63a7d11a993d1ba75d"; ShareResourceAction.Result res = action.call();

Python SDK

ShareResourceAction action = ShareResourceAction() action.resourceUuids = [b78e3c1026914c17916d0a3e37e3083a, 23c35149a4644fd0a230de71a52b2685] action.accountUuids = [56f8a1c0eac94d2da0913ac5ced688dc, fc4fdf4a31b746b8b8e7a7ddbd086f11] action.toPublic = false action.sessionId = "6f9572ac77904dcda0bbad3a15675865" ShareResourceAction.Result res = action.call()

Parent topic: 用户管理相关接口

创建用户组(CreateUserGroup)

API请求

URLs

POST zstack/v1/accounts/groups

Headers

Authorization: OAuth the-session-uuid

Body

{ "params": { "name": "usergroup" }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X POST -d '{"params":{"name":"usergroup"}}' \ http://localhost:8080/zstack/v1/accounts/groups

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |name|String|body(包含在params结构中)|资源名称| |0.6| |description (可选)|String|body(包含在params结构中)|资源的详细描述| |0.6| |resourceUuid (可选)|String|body(包含在params结构中)|资源UUID| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "uuid": "c6988be5a4ca47c994a08124993a8add", "accountUuid": "f6da67a4c77a4807910e0374e0f0ed63", "name": "usergroup" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventory|UserGroupInventory|详情参考inventory|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |accountUuid|String|账户UUID|0.6| |name|String|资源名称|0.6| |description|String|资源的详细描述|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

CreateUserGroupAction action = new CreateUserGroupAction(); action.name = "usergroup"; action.sessionId = "dbd9237abef344b0b0ddbb947e0c993d"; CreateUserGroupAction.Result res = action.call();

Python SDK

CreateUserGroupAction action = CreateUserGroupAction() action.name = "usergroup" action.sessionId = "d6434e6bb8c84d719804383abedc74e0" CreateUserGroupAction.Result res = action.call()

Parent topic: 用户管理相关接口

删除用户组(DeleteUserGroup)

API请求

URLs

DELETE/v1/accounts/groups/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 644846d7b557441d91b3a64510cf7d4e" \ -X DELETE http://localhost:8080/zstack/v1/accounts/groups/bbaba82b92ac43c4b08d99acac63638f?

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid|String|url|资源的UUID,唯一标示该资源| |0.6| |deleteMode (可选)|String|body|删除模式| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

DeleteUserGroupAction action = new DeleteUserGroupAction(); action.uuid = "c58611a13aaa4a38ac7ca35883dff419"; action.deleteMode = "Permissive"; action.sessionId = "d0b45ce10eb14370a8dd67c407aa4815"; DeleteUserGroupAction.Result res = action.call();

Python SDK

DeleteUserGroupAction action = DeleteUserGroupAction() action.uuid = "ccf4eaf4caa9404c8b73a55b2ed7bcf6" action.deleteMode = "Permissive" action.sessionId = "d4ae98b8863c4af098e5fbe8d598a046" DeleteUserGroupAction.Result res = action.call()

Parent topic: 用户管理相关接口

查询用户组(QueryUserGroup)

API请求

URLs

GET zstack/v1/accounts/groups GET zstack/v1/accounts/groups/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 11c890164eb54fc199e4d76fc7d0968b" \ -X GET http://localhost:8080/zstack/v1/accounts/groups?q=name=test

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 6d9e697aff1d4831abaf95e08652cb19" \ -X GET http://localhost:8080/zstack/v1/accounts/groups/c3662f079370466583d4eb080ac889af

可查询字段

运行zstack-cli命令行工具,输入QueryUserGroup并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例

{ "inventories": [ { "uuid": "775eb58ab79a41c9803cc8ffc4996f80", "accountUuid": "a3511b57fa06498b85c6c7150770120e", "name": "usergroup" } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventories|List|详情参考inventories|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventories

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |accountUuid|String|账户UUID|0.6| |name|String|资源名称|0.6| |description|String|资源的详细描述|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

QueryUserGroupAction action = new QueryUserGroupAction(); action.conditions = asList("name=test"); action.sessionId = "b920d6d5574e48eb917b3b92d2c9147d"; QueryUserGroupAction.Result res = action.call();

Python SDK

QueryUserGroupAction action = QueryUserGroupAction() action.conditions = ["name=test"] action.sessionId = "dcf0980272b743ad97ac3bcc2964344d" QueryUserGroupAction.Result res = action.call()

Parent topic: 用户管理相关接口

更新用户组(UpdateUserGroup)

API请求

URLs

PUT zstack/v1/accounts/groups/actions

Headers

Authorization: OAuth the-session-uuid

Body

{ "updateUserGroup": { "uuid": "41c1fb7a12f34ae9b81faed885019dfc", "name": "newname" }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X PUT -d '{"updateUserGroup":{"uuid":"3bad0f7e529c389d8510a4f327db632a","name":"newname"}}' \ http://localhost:8080/zstack/v1/accounts/groups/actions

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid|String|body(包含在updateUserGroup结构中)|资源的UUID,唯一标示该资源| |0.6| |name (可选)|String|body(包含在updateUserGroup结构中)|资源名称| |0.6| |description (可选)|String|body(包含在updateUserGroup结构中)|资源的详细描述| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "uuid": "b050b1beb08744e890d9980acbfd1595", "accountUuid": "b3a651d6cb6244c1bb25128520a89d25", "name": "newname" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventory|UserGroupInventory|详情参考inventory|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |accountUuid|String|账户UUID|0.6| |name|String|资源名称|0.6| |description|String|资源的详细描述|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

UpdateUserGroupAction action = new UpdateUserGroupAction(); action.uuid = "12a5413d1d1b4858b57edb47043dd305"; action.name = "newname"; action.sessionId = "3c8fc80478ed4d0c9306b6aee3186d65"; UpdateUserGroupAction.Result res = action.call();

Python SDK

UpdateUserGroupAction action = UpdateUserGroupAction() action.uuid = "0f2e2be28f92496ab7e72ca890f4c01e" action.name = "newname" action.sessionId = "f35be8c41ba442369e2bd4db4a8eddc8" UpdateUserGroupAction.Result res = action.call()

Parent topic: 用户管理相关接口

添加到用户组(AddUserToGroup)

API请求

URLs

POST zstack/v1/accounts/groups/{groupUuid}/users

Headers

Authorization: OAuth the-session-uuid

Body

{ "params": { "userUuid": "cbe08fd54e10427599928e1a19cd7093" }, "systemTags": [], "userTags": [] }

上述示例中systemTags、userTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X POST -d '{"params":{"userUuid":"74b4004fa0e23b2abb8ea8a6b3e28e25"}}' \ http://localhost:8080/zstack/v1/accounts/groups/2bca6534b91234f680605578e194da06/users

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |userUuid|String|body(包含在params结构中)|用户UUID| |0.6| |groupUuid|String|url|用户组UUID| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

AddUserToGroupAction action = new AddUserToGroupAction(); action.userUuid = "a2663e0a471a43d2bd292e52ed864c3c"; action.groupUuid = "70370a84e82a48c1904b979993ce93e6"; action.sessionId = "27a0e742c07b4f61b3294d0b445412d6"; AddUserToGroupAction.Result res = action.call();

Python SDK

AddUserToGroupAction action = AddUserToGroupAction() action.userUuid = "f6a9851e3d674688bf3e4edbd12d0c4f" action.groupUuid = "89839df4528c4742a6825a2086838394" action.sessionId = "cefd7bb2ac4b4ff98ab78d484631678d" AddUserToGroupAction.Result res = action.call()

Parent topic: 用户管理相关接口

绑定策略到用户组(AttachPolicyToUserGroup)

API请求

URLs

POST zstack/v1/accounts/groups/{groupUuid}/policies

Headers

Authorization: OAuth the-session-uuid

Body

{ "params": { "policyUuid": "8ee874eddba34ff28a519e213e6f86c2" }, "systemTags": [], "userTags": [] }

上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X POST -d '{"params":{"policyUuid":"ba7797e0c5753575a3873077f3490206"}}' \ http://localhost:8080/zstack/v1/accounts/groups/2bb2a8ab923639e3b3fb51e5f5e31d0c/policies

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |policyUuid|String|body(包含在params结构中)|权限策略UUID| |0.6| |groupUuid|String|url|用户组UUID| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

AttachPolicyToUserGroupAction action = new AttachPolicyToUserGroupAction(); action.policyUuid = "88abe0bf6f594688968a41049a029ab1"; action.groupUuid = "bae62f7a52774a48abf0e2deacd6fd97"; action.sessionId = "e6c356a17cf24f4998b190da9f40fbb7"; AttachPolicyToUserGroupAction.Result res = action.call();

Python SDK

AttachPolicyToUserGroupAction action = AttachPolicyToUserGroupAction() action.policyUuid = "94f0a40a0cf44a7aa9d0882d57e1e3ed" action.groupUuid = "ff8e9c24cf154761b3e020d3e8fd934e" action.sessionId = "31c21d7dfe7b4128ae4af3e46125a8ff" AttachPolicyToUserGroupAction.Result res = action.call()

Parent topic: 用户管理相关接口

将策略从用户组解绑(DetachPolicyFromUserGroup)

API请求

URLs

DELETE/v1/accounts/groups/{groupUuid}/policies/{policyUuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 7cbe5df712b84b769016bdc8484f7266" \ -X DELETE http://localhost:8080/zstack/v1/accounts/groups/85f398f824c0406e97a1b8dac847c1b4\ /policies/904ff8584f7040dc9871b109210fe497?

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |policyUuid|String|url|权限策略UUID| |0.6| |userUuid|String|url|用户UUID| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

DetachPolicyFromUserGroupAction action = new DetachPolicyFromUserGroupAction(); action.policyUuid = "c0589bc7c00040b296316c0e12b51d59"; action.groupUuid = "75b38fea53fd420cadd9a3d627ffd5e4"; action.sessionId = "617424262377430bb08f77ab856f3d15"; DetachPolicyFromUserGroupAction.Result res = action.call();

Python SDK

DetachPolicyFromUserGroupAction action = DetachPolicyFromUserGroupAction() action.policyUuid = "ae4c808ce9dc4117b16ba7a7efc09cd0" action.groupUuid = "0870a2177efe4175be538230874fda53" action.sessionId = "9e8cb02459eb4cdda5dca116d74d13fa" DetachPolicyFromUserGroupAction.Result res = action.call()

Parent topic: 用户管理相关接口

从用户组中移除用户(RemoveUserFromGroup)

API请求

URLs

DELETE/v1/accounts/groups/{groupUuid}/users/{userUuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl \ -H "Content-Type: application/json" \ -H "Authorization: OAuth c987f75c01f4474e94964d7176ce80d2" \ -X DELETE http://localhost:8080/zstack/v1/accounts/groups/5ca878437a064e7d9cabc46c5235e846/users\ /d343976dbd774d97b3989579bb3f8638?

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |userUuid|String|url|用户UUID| |0.6| |groupUuid|String|url|用户组UUID| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

RemoveUserFromGroupAction action = new RemoveUserFromGroupAction(); action.userUuid = "0ee5933b7a17453f875743a0007d93a3"; action.groupUuid = "20096dc990074ef193f9588caf976074"; action.sessionId = "ad3401f277c64ab5804e3b85beb76b6f"; RemoveUserFromGroupAction.Result res = action.call();

Python SDK

RemoveUserFromGroupAction action = RemoveUserFromGroupAction() action.userUuid = "d2c58c22b6bb4f3e85756cf8c2fcc58e" action.groupUuid = "779b3a172ab14c16a143792a623e73d2" action.sessionId = "2d13b900e72342f78266c309f0ec5f92" RemoveUserFromGroupAction.Result res = action.call()

Parent topic: 用户管理相关接口

创建用户(CreateUser)

API请求

URLs

POST zstack/v1/accounts/users

Headers

Authorization: OAuth the-session-uuid

Body

{ "params": { "name": "testuser", "password": "testpassword" }, "systemTags": [], "userTags": [] }

上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X POST -d '{"params":{"name":"testuser","password":"testpassword"}}' \ http://localhost:8080/zstack/v1/accounts/users

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |name|String|body(包含在params结构中)|用户名称| |0.6| |password|String|body(包含在params结构中)|密码| |0.6| |description (可选)|String|body(包含在params结构中)|资源的详细描述| |0.6| |resourceUuid (可选)|String|body(包含在params结构中)|资源UUID| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "uuid": "b30ad4ad36864c659a8ae06e803f8d25", "accountUuid": "22614a98cbfe4eca9305d398b2f10ff2", "name": "testuser" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventory|UserInventory|详情参考inventory|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |accountUuid|String|账户UUID|0.6| |name|String|资源名称|0.6| |description|String|资源的详细描述|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

CreateUserAction action = new CreateUserAction(); action.name = "testuser"; action.password = "testpassword"; action.sessionId = "f0548be1ffec469fac0ce3e343be7ffe"; CreateUserAction.Result res = action.call();

Python SDK

CreateUserAction action = CreateUserAction() action.name = "testuser" action.password = "testpassword" action.sessionId = "f87ead16d2934a2096b55b8532175722" CreateUserAction.Result res = action.call()

Parent topic: 用户管理相关接口

删除用户(DeleteUser)

API请求

URLs

DELETE/v1/accounts/users/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 18ec08fb5cbe41ca905ba15807bb5c5a" \ -X DELETE http://localhost:8080/zstack/v1/accounts/users/8298cc2536ec4fce83993ba9d6f83ced?

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid|String|url|资源的UUID,唯一标示该资源| |0.6| |deleteMode (可选)|String|body|删除模式| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

DeleteUserAction action = new DeleteUserAction(); action.uuid = "21e499f4359842db8f9d775411045679"; action.deleteMode = "Permissive"; action.sessionId = "46d07fa8aee244e4bb997f1b8b63d582"; DeleteUserAction.Result res = action.call();

Python SDK

DeleteUserAction action = DeleteUserAction() action.uuid = "80520c9850334934aa67b56c47923a7a" action.deleteMode = "Permissive" action.sessionId = "f7070ae8f9bc4bca8e272da70171fdeb" DeleteUserAction.Result res = action.call()

Parent topic: 用户管理相关接口

查询用户(QueryUser)

API请求

URLs

GET zstack/v1/accounts/users GET zstack/v1/accounts/users/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 87ed43cda766436c94c3fd5afcbb21fc" \ -X GET http://localhost:8080/zstack/v1/accounts/users?q=name=test

curl \ -H "Content-Type: application/json" \ -H "Authorization: OAuth 15b9e66544f84e0495e232ec64596c90" \ -X GET http://localhost:8080/zstack/v1/accounts/users/cf0dde42f06e498eaf41fc4b1c2fe4fa

可查询字段

运行zstack-cli命令行工具,输入QueryUser并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例

{ "inventories": [ { "uuid": "b369a13fbbf64812802612040590a682", "accountUuid": "9cf0fc6c3d8146dab03a5727da5ebe2b", "name": "testuser" } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventories|List|详情参考inventories|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventories

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |accountUuid|String|账户UUID|0.6| |name|String|资源名称|0.6| |description|String|资源的详细描述|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

QueryUserAction action = new QueryUserAction(); action.conditions = asList("name=test"); action.sessionId = "6dd33c53214d4673ae3805f618c1726b"; QueryUserAction.Result res = action.call();

Python SDK

QueryUserAction action = QueryUserAction() action.conditions = ["name=test"] action.sessionId = "66e0b1c03d8b4ec68a54c37ba917548b" QueryUserAction.Result res = action.call()

Parent topic: 用户管理相关接口

更新用户(UpdateUser)

API请求

URLs

PUT zstack/v1/accounts/users/actions

Headers

Authorization: OAuth the-session-uuid

Body

{ "updateUser": { "uuid": "849586db1ac341bf8d4670a62ed9b8ee", "name": "new" }, "systemTags": [], "userTags": [] }

上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X PUT -d '{"updateUser":{"uuid":"15c7ee4e52f23f36af2b64ef54b0e128","name":"new"}}' \ http://localhost:8080/zstack/v1/accounts/users/actions

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid (可选)|String|body(包含在updateUser结构中)|资源的UUID,唯一标示该资源| |0.6| |password (可选)|String|body(包含在updateUser结构中)|密码| |0.6| |name (可选)|String|body(包含在updateUser结构中)|用户名称| |0.6| |description (可选)|String|body(包含在updateUser结构中)|资源的详细描述| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

UpdateUserAction action = new UpdateUserAction(); action.uuid = "2faab564de0440c2bbd98606a63a5a3b"; action.name = "new"; action.sessionId = "4f6e13d3b9d94413bf22375065213c4a"; UpdateUserAction.Result res = action.call();

Python SDK

UpdateUserAction action = UpdateUserAction() action.uuid = "bb6e95360dce42749f3bfd938cd83fec" action.name = "new" action.sessionId = "f305112833c142bc8f5ee69f76c0c755" UpdateUserAction.Result res = action.call()

Parent topic: 用户管理相关接口

使用用户身份登录(LogInByUser)

API请求

URLs

PUT zstack/v1/accounts/users/login

Body

{ "logInByUser": { "accountName": "test", "userName": "user", "password": "password" }, "systemTags": [], "userTags": [] }

上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -X PUT -d '{"logInByUser":{"accountName":"test","userName":"user","password":"password"}}' \ http://localhost:8080/zstack/v1/accounts/users/login

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |accountUuid (可选)|String|body(包含在logInByUser结构中)|账户UUID| |0.6| |accountName (可选)|String|body(包含在logInByUser结构中)|账户名称| |0.6| |userName|String|body(包含在logInByUser结构中)|用户名称| |0.6| |password|String|body(包含在logInByUser结构中)|密码| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "uuid": "b5a610a81379429eb77545a016968a75", "accountUuid": "21f081c4696b4e8492aa0afdef9d8e5b", "expiredDate": "Jun 7, 2017 9:20:37 PM" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventory|SessionInventory|详情参考inventory|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |accountUuid|String|账户UUID|0.6| |userUuid|String|用户UUID|0.6| |expiredDate|Timestamp|会话过期日期|0.6| |createDate|Timestamp|创建时间|0.6|

SDK示例

Java SDK

LogInByUserAction action = new LogInByUserAction(); action.accountName = "test"; action.userName = "user"; action.password = "password"; LogInByUserAction.Result res = action.call();

Python SDK

LogInByUserAction action = LogInByUserAction() action.accountName = "test" action.userName = "user" action.password = "password" LogInByUserAction.Result res = action.call()

Parent topic: 用户管理相关接口

绑定一条策略到用户(AttachPolicyToUser)

API请求

URLs

POST zstack/v1/accounts/users/{userUuid}/policies

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X POST http://localhost:8080/zstack/v1/accounts/users/0967bf18e5e13219ae29e918924a2dcf/policies

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |userUuid|String|url|用户UUID| |0.6| |policyUuid|String|body|权限策略UUID| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

AttachPolicyToUserAction action = new AttachPolicyToUserAction(); action.userUuid = "75e68a1812054f64acf656456b03baa4"; action.policyUuid = "d7d9402395b148cf8d78f280f5125f26"; action.sessionId = "51d7fd9a98194317b65daa550bade794"; AttachPolicyToUserAction.Result res = action.call();

Python SDK

AttachPolicyToUserAction action = AttachPolicyToUserAction() action.userUuid = "7c561e42ecd540c2a4e49b4c1f14098f" action.policyUuid = "eb1ebb663e73491a973be09825ab064d" action.sessionId = "d1cceff7e99d4310a5f15d5d822f3c26" AttachPolicyToUserAction.Result res = action.call()

Parent topic: 用户管理相关接口

将一条策略从用户解绑(DetachPolicyFromUser)

API请求

URLs

DELETE/v1/accounts/groups/{groupUuid}/policies/{policyUuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 7cbe5df712b84b769016bdc8484f7266" \ -X DELETE http://localhost:8080/zstack/v1/accounts/groups/85f398f824c0406e97a1b8dac847c1b4/policies\ /904ff8584f7040dc9871b109210fe497?

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |policyUuid|String|url|权限策略UUID| |0.6| |groupUuid|String|url|用户组UUID| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

DetachPolicyFromUserGroupAction action = new DetachPolicyFromUserGroupAction(); action.policyUuid = "c0589bc7c00040b296316c0e12b51d59"; action.groupUuid = "75b38fea53fd420cadd9a3d627ffd5e4"; action.sessionId = "617424262377430bb08f77ab856f3d15"; DetachPolicyFromUserGroupAction.Result res = action.call();

Python SDK

DetachPolicyFromUserGroupAction action = DetachPolicyFromUserGroupAction() action.policyUuid = "ae4c808ce9dc4117b16ba7a7efc09cd0" action.groupUuid = "0870a2177efe4175be538230874fda53" action.sessionId = "9e8cb02459eb4cdda5dca116d74d13fa" DetachPolicyFromUserGroupAction.Result res = action.call()

Parent topic: 用户管理相关接口

绑定多条策略到用户(AttachPoliciesToUser)

API请求

URLs

POST zstack/v1/accounts/users/{userUuid}/policy-collection

Headers

Authorization: OAuth the-session-uuid

Body

{ "params": { "policyUuids": [ "a511e7401e76451db1d1a0f308164d8a", "d2653f82c54049179a091e6bc410a8ba" ] }, "systemTags": [], "userTags": [] }

上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X POST -d '{"params":{"policyUuids":["619ab16981e93fb28032402506ec52f7","ca7daca8b4a739f1a03d1fdccc988c42"]}}' \ http://localhost:8080/zstack/v1/accounts/users/cd7318ea58d036b1aab8481dfc47c4fe/policy-collection

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |userUuid|String|url|用户UUID| |0.6| |policyUuids|List|body(包含在params结构中)|策略的UUID列表| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

AttachPoliciesToUserAction action = new AttachPoliciesToUserAction(); action.userUuid = "13aa76b1909b4536a89b124c62131deb"; action.policyUuids = asList("a7a2ae2b06a946838196d8d673d31b1c","9a7f6d7a54404d7793267a39669269da"); action.sessionId = "6ffafe6f021341ab8ada83c077bfc7a5"; AttachPoliciesToUserAction.Result res = action.call();

Python SDK

AttachPoliciesToUserAction action = AttachPoliciesToUserAction() action.userUuid = "b3d44e5b2b7f43aa815efb4c146b2a9f" action.policyUuids = [a957c0dbe1794323a61c8268055f5140, 4b154d22a70e44de9ab2d1f818407a0e] action.sessionId = "adbbb5aa92844bc5895f8d2bada71251" AttachPoliciesToUserAction.Result res = action.call()

Parent topic: 用户管理相关接口

将多条策略从用户解绑(DetachPoliciesFromUser)

API请求

URLs

DELETE/v1/accounts/users/{userUuid}/policies

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 32ab85539534426ea5e7495efdc7cd72" \ -X DELETE http://localhost:8080/zstack/v1/accounts/users/30300b8350714679aa490aa80bcb0d3f/policies?

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |policyUuids|List|body|策略UUID列表| |0.6| |userUuid|String|url|用户UUID| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

DetachPoliciesFromUserAction action = new DetachPoliciesFromUserAction(); action.policyUuids = asList("92ac3dbba2764bc0a0d740a8a80c7942","d11783b09ee14bffbdd16ca856c42b7f"); action.userUuid = "1577443fec9746b9a47656f9e7f1f81a"; action.sessionId = "3d80ce5358a140f89c9942760a83b40b"; DetachPoliciesFromUserAction.Result res = action.call();

Python SDK

DetachPoliciesFromUserAction action = DetachPoliciesFromUserAction() action.policyUuids = [e3b7ef2416bb4960b592e817a626b351, 1e61ce554f6647099f7545fe49fccea9] action.userUuid = "11edbda7d9d5406f9beb1e9dc9ff2b3c" action.sessionId = "d04ed26067504e77905b8651927034b1" DetachPoliciesFromUserAction.Result res = action.call()

Parent topic: 用户管理相关接口

创建策略(CreatePolicy)

API请求

URLs

POST zstack/v1/accounts/policies

Headers

Authorization: OAuth the-session-uuid

Body

{ "params": { "name": "USER-RESET-PASSWORD", "statements": [ { "name": "user-reset-password-5d0159c128e14758b2c66a319e6cb0b8", "effect": "Allow", "actions": [ "identity:APIUpdateUserMsg" ] } ] }, "systemTags": [], "userTags": [] }

上述示例中systemTags、userTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X POST -d '{"params":{"name":"USER-RESET-PASSWORD","statements":[{"name":"user-reset-password-f5f9e3b82e9e39448c1b09b10d0211c8","effect":"Allow","actions":["identity:APIUpdateUserMsg"]}]}}' \ http://localhost:8080/zstack/v1/accounts/policies

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |name|String|body(包含在params结构中)|资源名称| |0.6| |description (可选)|String|body(包含在params结构中)|资源的详细描述| |0.6| |statements|List|body(包含在params结构中)|策略声明| |0.6| |resourceUuid (可选)|String|body(包含在params结构中)|资源UUID| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "statements": [ { "name": "user-reset-password-e0a7a495b8384b3ca3922c31b133f318", "effect": "Allow", "actions": [ "identity:APIUpdateUserMsg" ] } ], "name": "USER-RESET-PASSWORD", "uuid": "e0a7a495b8384b3ca3922c31b133f318", "accountUuid": "14cf676b762f4defb60a67e2ff212ce5" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventory|PolicyInventory|详情参考inventory|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |name|String|资源名称|0.6| |uuid|String|资源的UUID,唯一标示该资源|0.6| |accountUuid|String|账户UUID|0.6| |statements|List|详情参考statements|0.6|

#statements

|名字|类型|描述|起始版本| |--|--|--|----| |name|String|资源名称|0.6| |principals|List| |0.6| |actions|List|一个匹配API的字符串列表|0.6| |resources|List|资源列表|0.6| |effect|StatementEffect|详情参考effect|0.6|

#effect

|名字|类型|描述|起始版本| |--|--|--|----| |name|String|资源名称|0.6| |ordinal|int|序号|0.6|

SDK示例

Java SDK

CreatePolicyAction action = new CreatePolicyAction(); action.name = "USER-RESET-PASSWORD"; action.statements = asList([name:user-reset-password-e3d9eaa96d194f3e8c5c1f68126433f8, effect:Allow, actions:[identity:APIUpdateUserMsg]]); action.sessionId = "e6e07201e51f410f92f9f5cca362ae7c"; CreatePolicyAction.Result res = action.call();

Python SDK

CreatePolicyAction action = CreatePolicyAction() action.name = "USER-RESET-PASSWORD" action.statements = [[name:user-reset-password-ee67ad94c9c845c7a84610489e9b6b38, effect:Allow, actions:[identity:APIUpdateUserMsg]]] action.sessionId = "f66df3c4bcd041e1ba3427cc29a214bb" CreatePolicyAction.Result res = action.call()

Parent topic: 用户管理相关接口

删除策略(DeletePolicy)

API请求

URLs

DELETE/v1/accounts/policies/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 93d4e3a2a9284ca39ce66dd16fe4969d" \ -X DELETE http://localhost:8080/zstack/v1/accounts/policies/cb26b0dc3e884b778340866f8874d0a7?

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid|String|url|资源的UUID,唯一标示该资源| |0.6| |deleteMode (可选)|String|body|删除模式| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

DeletePolicyAction action = new DeletePolicyAction(); action.uuid = "8016dfed1d21461282c0bb727caf64b0"; action.deleteMode = "Permissive"; action.sessionId = "5a07babcc136411ebbf2e44dd82ff120"; DeletePolicyAction.Result res = action.call();

Python SDK

DeletePolicyAction action = DeletePolicyAction() action.uuid = "ada726f1b3d24fa38d0989d9dd15dc92" action.deleteMode = "Permissive" action.sessionId = "5886ee75912e4fd8adc38004de563eca" DeletePolicyAction.Result res = action.call()

Parent topic: 用户管理相关接口

查询策略(QueryPolicy)

API请求

URLs

GET zstack/v1/accounts/policies GET zstack/v1/accounts/policies/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 766a381351a44b6b8fc4c20effb62f65" \ -X GET http://localhost:8080/zstack/v1/accounts/policies?q=name=test

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 8d17ab76304a4e50871d4a2f189e32de" \ -X GET http://localhost:8080/zstack/v1/accounts/policies/dd36dffd40d14081a94ff4a024ee54ce

可查询字段

运行zstack-cli命令行工具,输入QueryPolicy并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例

{ "inventories": [ { "statements": [ { "name": "user-reset-password-10e0d5dc0a4846c8b7e2e204aa014370", "effect": "Allow", "actions": [ "identity:APIUpdateUserMsg" ] } ], "name": "USER-RESET-PASSWORD", "uuid": "10e0d5dc0a4846c8b7e2e204aa014370", "accountUuid": "2884beb74bff43569096365a90e696fb" } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventories|List|详情参考inventories|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventories

|名字|类型|描述|起始版本| |--|--|--|----| |name|String|资源名称|0.6| |uuid|String|资源的UUID,唯一标示该资源|0.6| |accountUuid|String|账户UUID|0.6| |statements|List|详情参考statements|0.6|

#statements

|名字|类型|描述|起始版本| |--|--|--|----| |name|String|资源名称|0.6| |principals|List| |0.6| |actions|List|一个匹配API的字符串列表|0.6| |resources|List|资源列表|0.6| |effect|StatementEffect|详情参考effect|0.6|

#effect

|名字|类型|描述|起始版本| |--|--|--|----| |name|String|资源名称|0.6| |ordinal|int|序号|0.6|

SDK示例

Java SDK

QueryPolicyAction action = new QueryPolicyAction(); action.conditions = asList("name=test"); action.sessionId = "12d48774c4b94e35a62cd8d715a2f6a5"; QueryPolicyAction.Result res = action.call();

Python SDK

QueryPolicyAction action = QueryPolicyAction() action.conditions = ["name=test"] action.sessionId = "a0233a244b7e41ca9aa1322294dfd4a6" QueryPolicyAction.Result res = action.call()

Parent topic: 用户管理相关接口

查询配额(QueryQuota)

API请求

URLs

GET zstack/v1/accounts/quotas

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth c8070838ec0249cabfe576fc519d54b4" \ -X GET http://localhost:8080/zstack/v1/accounts/quotas?q=name=test

可查询字段

运行zstack-cli命令行工具,输入QueryQuota并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例

{ "inventories": [ { "name": "quota", "identityUuid": "bdb6f9724a0d40d69ffa47856a916f93", "value": 20.0 } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventories|List|详情参考inventories|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventories

|名字|类型|描述|起始版本| |--|--|--|----| |name|String|资源名称|0.6| |identityUuid|String|身份UUID(账户UUID,用户UUID)|0.6| |identityType|String|身份类型(账户,用户)|0.6| |value|Long|默认配额值|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6| |createDate|Timestamp|创建时间|0.6|

SDK示例

Java SDK

QueryQuotaAction action = new QueryQuotaAction(); action.conditions = asList("name=test"); action.sessionId = "c9097f025877470d92b5f07e1bdd47f4"; QueryQuotaAction.Result res = action.call();

Python SDK

QueryQuotaAction action = QueryQuotaAction() action.conditions = ["name=test"] action.sessionId = "c72011b5cc94485dadac4d6be216bb86" QueryQuotaAction.Result res = action.call()

Parent topic: 用户管理相关接口

更新配额(UpdateQuota)

API请求

URLs

PUT zstack/v1/accounts/quotas/actions

Headers

Authorization: OAuth the-session-uuid

Body

{ "updateQuota": { "identityUuid": "55dc6ddab7a749d5b7e38b684daf4489", "name": "quotaname", "value": 20.0 }, "systemTags": [], "userTags": [] }

上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X PUT -d '{"updateQuota":{"identityUuid":"4d45e6c7787733979415760d2077fca0","name":"quotaname","value":20.0}}' \ http://localhost:8080/zstack/v1/accounts/quotas/actions

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |identityUuid|String|body(包含在updateQuota结构中)|身份实体的UUID(账户的)| |0.6| |name|String|body(包含在updateQuota结构中)|资源名称| |0.6| |value|long|body(包含在updateQuota结构中)|配额值| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "name": "quota", "identityUuid": "991e8d478a404416b2ac60ba19a5001f", "value": 20.0 } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventory|QuotaInventory|详情参考inventory|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |name|String|资源名称|0.6| |identityUuid|String|身份UUID(账户UUID,用户UUID)|0.6| |identityType|String|身份类型(账户,用户)|0.6| |value|Long|默认配额值|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6| |createDate|Timestamp|创建时间|0.6|

SDK示例

Java SDK

UpdateQuotaAction action = new UpdateQuotaAction(); action.identityUuid = "38038cff62c74a638be4be37dd005aeb"; action.name = "quotaname"; action.value = 20.0; action.sessionId = "00e4d2ccc6c44909886bddcd83c8362c"; UpdateQuotaAction.Result res = action.call();

Python SDK

UpdateQuotaAction action = UpdateQuotaAction() action.identityUuid = "bf4b6809cf58435b8c39764e38e291e4" action.name = "quotaname" action.value = 20.0 action.sessionId = "cf6c686607704665a5ced86bb8824994" UpdateQuotaAction.Result res = action.call()

Parent topic: 用户管理相关接口

获取资源名称(GetResourceNames)

API请求

URLs

GET zstack/v1/resources/names

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 00c30442f2dc4b8c8473c19c7e74e8d3" \ -X GET http://localhost:8080/zstack/v1/resources\names?uuids=e9bfb5dac23940faabfacffc78c08515&uuids=360b13b4c34c473bb025457853ed11e2

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuids|List|query|资源的UUID列表| |0.6| |systemTags (可选)|List|query| | |0.6| |userTags (可选)|List|query| | |0.6|

API返回

返回示例

{ "inventories": [ { "uuid": "924c3b8f2c6243009b344663fe058c8a", "resourceName": "zone", "resourceType": "ZoneVO" }, { "uuid": "94eb4667d8d444108410cc9d4a3a06df", "resourceName": "vm", "resourceType": "VmInstanceVO" } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|2.0| |inventories|List|详情参考inventories|2.0|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventories

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|2.0| |resourceName|String|资源名称|2.0| |resourceType|String|资源类型,例如虚拟机为VmInstanceVO|2.0|

SDK示例

Java SDK

GetResourceNamesAction action = new GetResourceNamesAction(); action.uuids = asList("070e5ad04d0642e49bcdecf4d823756f","b5abed013df445639a3a186457e2e5cf"); action.sessionId = "7504d193416f4ba8972b18171fd8b8a5"; GetResourceNamesAction.Result res = action.call();

Python SDK

GetResourceNamesAction action = GetResourceNamesAction() action.uuids = [312b7575044b4e839d537a57c19e08dd, 1f2630f284f7473b8dfcf9768dedea71] action.sessionId = "0845cfcd381f494298408b55858027ec" GetResourceNamesAction.Result res = action.call()

Parent topic: 用户管理相关接口

查询共享资源(QuerySharedResource)

API请求

URLs

GET zstack/v1/accounts/resources

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 3e4cb7624a3e4fb29a2cc4ff78886dee" \ -X GET http://localhost:8080/zstack/v1/accounts/resources?q=accountUuid=8d10cb2b1713476a9bea6dc858440f43

可查询字段

运行zstack-cli命令行工具,输入QuerySharedResource并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例

{ "inventories": [ { "ownerAccountUuid": "459f08b3915d4c06817e36587bd91fbb", "receiverAccountUuid": "3de68725726544209999d5ec8172926e", "toPublic": false, "resourceType": "ImageVO", "resourceUuid": "01f2f1309e9f4d67955a0648df6963a0" } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventories|List|详情参考inventories|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventories

|名字|类型|描述|起始版本| |--|--|--|----| |ownerAccountUuid|String|所有者账户UUID|0.6| |receiverAccountUuid|String|接受者账户UUID|0.6| |toPublic|Boolean|是否全局共享|0.6| |resourceType|String|资源类型|0.6| |resourceUuid|String|资源UUID|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6| |createDate|Timestamp|创建时间|0.6|

SDK示例

Java SDK

QuerySharedResourceAction action = new QuerySharedResourceAction(); action.conditions = asList("accountUuid=f96b5eeb13664c279c7cf35b62926b0a"); action.sessionId = "3cd36c2836ab4997ae18ef5d5e834ae7"; QuerySharedResourceAction.Result res = action.call();

Python SDK

QuerySharedResourceAction action = QuerySharedResourceAction() action.conditions = ["accountUuid=58c6de28e4854df8b15849d9317aaeac"] action.sessionId = "00609fd22d5a4eb4bfb2abcd5fcf2fef" QuerySharedResourceAction.Result res = action.call()

Parent topic: 用户管理相关接口

解除资源共享(RevokeResourceSharing)

API请求

URLs

PUT zstack/v1/accounts/resources/actions

Headers

Authorization: OAuth the-session-uuid

Body

{ "revokeResourceSharing": { "resourceUuids": [ "dcaffbb395944eb28df4e63a2a1b9f8d", "47fc53a8addf4daea866457f633eca49" ], "toPublic": false, "accountUuids": [ "06c6efc4c8b34488a7bc42a55df36ff8", "6eea9ce615d341bfa7737e730088e9f3" ], "all": false }, "systemTags": [], "userTags": [] }

上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X PUT -d '{"revokeResourceSharing":{"resourceUuids":["6551ce5374243f14875351219cdb69ba","18501632374c331692e10ab976f56e28"],"toPublic":false,"accountUuids":["9a0c56a8bcbd31edbd384b28b8ffeffc","3627b63ad55939cf8df5fa4848abd6f2"],"all":false}}' \ http://localhost:8080/zstack/v1/accounts/resources/actions

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |resourceUuids|List|body(包含在revokeResourceSharing结构中)|资源UUID列表| |0.6| |toPublic (可选)|boolean|body(包含在结构中)|全局共享| |0.6| |accountUuids (可选)|List|body(包含在revokeResourceSharing结构中)Note: all参数设为false时,账户UUID不能为空

|账户UUID列表| |0.6| |all (可选)|boolean|body(包含在revokeResourceSharing结构中)| | |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

RevokeResourceSharingAction action = new RevokeResourceSharingAction(); action.resourceUuids = asList("8c4c9fa690ff4e2696dbe2be4b020bb1","88fc827d508a41cf9d1384f0139c5c1d"); action.toPublic = false; action.accountUuids = asList("5272e8a31e854ee38d136f772c4f6fa9","a8a552a327f44f09a76d96d45a655150"); action.all = false; action.sessionId = "5a025e658940490c98609cdb5251b83d"; RevokeResourceSharingAction.Result res = action.call();

Python SDK

RevokeResourceSharingAction action = RevokeResourceSharingAction() action.resourceUuids = [0f849f45aaeb4c23b74821030825d785, cb9a412086fc49d5ae24782b40aedbe9] action.toPublic = false action.accountUuids = [bc7666d3e7fb4eaa9683bf62cdd2df1e, 5046a88fdc7c40fc90b29c47b96176d5] action.all = false action.sessionId = "b6b1787762424c2bb81ac6d8fbac84b4" RevokeResourceSharingAction.Result res = action.call()

Parent topic: 用户管理相关接口

变更资源所有者(ChangeResourceOwner)

API请求

URLs

POST zstack/v1/account/{accountUuid}/resources

Headers

Authorization: OAuth the-session-uuid

Body

{ "params": { "resourceUuid": "d2ed71c00bfb40128df81f493935b6e1" }, "systemTags": [], "userTags": [] }

上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X POST -d '{"params":{"resourceUuid":"abfee8286ae43b19a02179cfe37b3294"}}' \ http://localhost:8080/zstack/v1/account/e9da3eb01abc31c78ac24dec8c8c36b5/resources

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |accountUuid|String|url|账户UUID| |0.6| |resourceUuid|String|body(包含在params结构中)|资源UUID| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "id": 1.0, "accountUuid": "da02579d9641446db9a6d37a8c80091e", "resourceUuid": "81bab520db724e5e9336513f9132e36e", "resourceType": "ImageVO", "isShared": false } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventory|AccountResourceRefInventory|详情参考inventory|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |accountUuid|String|账户UUID|0.6| |resourceUuid|String|资源UUID|0.6| |resourceType|String|资源类型|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

ChangeResourceOwnerAction action = new ChangeResourceOwnerAction(); action.accountUuid = "fc928d9a7aae4878bdc5c66c65047ece"; action.resourceUuid = "361e14e7b0164cfab336157439d01e0b"; action.sessionId = "41fbe11e8106405e9b80dc8c025f9375"; ChangeResourceOwnerAction.Result res = action.call();

Python SDK

ChangeResourceOwnerAction action = ChangeResourceOwnerAction() action.accountUuid = "d9830eb0fcc0421683821ee360519b3c" action.resourceUuid = "e05f53fe5c524567a328f4c36a19f22a" action.sessionId = "19a6e968033f45b4bcfbd22610bfbcd9" ChangeResourceOwnerAction.Result res = action.call()

Parent topic: 用户管理相关接口

检查API权限(CheckApiPermission)

API请求

URLs

PUT zstack/v1/accounts/permissions/actions

Headers

Authorization: OAuth the-session-uuid

Body

{ "checkApiPermission": { "userUuid": "70168720d76e4e3890604027c9f755a9", "apiNames": [ "APICheckApiPermissionMsg" ] }, "systemTags": [], "userTags": [] }

上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X PUT -d '{"checkApiPermission":{"userUuid":"927a64d62f9d3dd099743952a297b8c0","apiNames":["APICheckApiPermissionMsg"]}}' \ http://localhost:8080/zstack/v1/accounts/permissions/actions

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |userUuid (可选)|String|body(包含在checkApiPermission结构中)|用户UUID| |0.6| |apiNames|List|body(包含在checkApiPermission结构中)|API名称列表Note: 例如:

| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "APICheckApiPermissionMsg": "Allow" } }

|名字|类型|描述|起始版本| |--|--|--|----| |inventory|Map|API权限清单|0.6| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

SDK示例

Java SDK

CheckApiPermissionAction action = new CheckApiPermissionAction(); action.userUuid = "c12663e4e58a474dbd5ed36511876ccc"; action.apiNames = asList("APICheckApiPermissionMsg"); action.sessionId = "f855e33926484a679f19573e931c0894"; CheckApiPermissionAction.Result res = action.call();

Python SDK

CheckApiPermissionAction action = CheckApiPermissionAction() action.userUuid = "fa7addff47d84bf3bddd5f98defb8211" action.apiNames = [APICheckApiPermissionMsg] action.sessionId = "b9e0b4b8ee5a4051a1830fd247e9b896" CheckApiPermissionAction.Result res = action.call()

Parent topic: 用户管理相关接口

验证会话的有效性(ValidateSession)

API请求

URLs

GET zstack/v1/accounts/sessions/{sessionUuid}/valid

Curl示例

curl -H "Content-Type: application/json" \ -X GET http://localhost:8080/zstack/v1/accounts/sessions/52a1bfa21ef94cc6b7f70096c8a32a0c/valid?

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |sessionUuid|String|url|会话UUID| |0.6| |systemTags (可选)|List|query|系统标签| |0.6| |userTags (可选)|List|query|用户标签| |0.6|

API返回

返回示例

{ "validSession": true }

|名字|类型|描述|起始版本| |--|--|--|----| |valid|boolean|会话是否有效|0.6| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

SDK示例

Java SDK

ValidateSessionAction action = new ValidateSessionAction(); action.sessionId = "3f791329d8ed4f7bb4fb3eb2aa70527e"; ValidateSessionAction.Result res = action.call();

Python SDK

ValidateSessionAction action = ValidateSessionAction() action.sessionId = "763d6cb8d60d43a68de3a2b4e85cfc72" ValidateSessionAction.Result res = action.call()

Parent topic: 用户管理相关接口

更新会话(RenewSession)

API请求

URLs

PUT zstack/v1/accounts/sessions/{sessionUuid}/renew

Headers

Authorization: OAuth the-session-uuid

Body

{ "renewSession": { "duration": 100 }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X PUT -d '{"renewSession":{"duration":100.0}}' \ http://localhost:8080/zstack/v1/accounts/sessions/7b93b7648aea3c8d9109498a32288470/renew

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |sessionUuid|String|url|会话uuid| |0.6| |duration (可选)|Long|body(包含在renewSession结构中)| | |2.3| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "uuid": "dce673d8c6d53988b188b4ac34e7304d", "accountUuid": "fa58814a623d3778a8c91d11b74c6d38", "expiredDate": "Nov 14, 2017 10:20:57 PM" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventory|SessionInventory|详情参考inventory|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |accountUuid|String|账户UUID|0.6| |userUuid|String|用户UUID|0.6| |expiredDate|Timestamp|会话过期日期|0.6| |createDate|Timestamp|创建时间|0.6|

SDK示例

Java SDK

RenewSessionAction action = new RenewSessionAction(); action.sessionUuid = "7b93b7648aea3c8d9109498a32288470"; action.duration = 100; action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"; RenewSessionAction.Result res = action.call();

Python SDK

RenewSessionAction action = RenewSessionAction() action.sessionUuid = "7b93b7648aea3c8d9109498a32288470" action.duration = 100 action.sessionId = "b86c9016b4f24953a9edefb53ca0678c" RenewSessionAction.Result res = action.call()

Parent topic: 用户管理相关接口

退出当前登录状态(LogOut)

API请求

URLs

DELETE/v1/accounts/sessions/{sessionUuid}

Curl示例

curl -H "Content-Type: application/json" \ -X DELETE http://localhost:8080/zstack/v1/accounts/sessions/2f1ebb34e54f4239bbd2080088804194?

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |sessionUuid (可选)|String|url|会话UUID| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

LogOutAction action = new LogOutAction(); action.sessionId = "0c7e729fb59945938752cd4ec99c2a94"; LogOutAction.Result res = action.call();

Python SDK

LogOutAction action = LogOutAction() action.sessionId = "1cb84b3f5713432aaf42bc230c32aa20" LogOutAction.Result res = action.call()

Parent topic: 用户管理相关接口

计费管理相关接口

创建资源价格(CreateResourcePrice)

API请求

URLs

POST zstack/v1/billings/prices

Headers

Authorization: OAuth the-session-uuid

Body

{ "params": { "resourceName": "cpu", "timeUnit": "s", "price": 100.0, "dateInLong": 0.0 }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth cc882c434d65428091449452ab5eb2e3" \ -X POST -d '{"params":{"resourceName":"cpu","timeUnit":"s","price":100.0,"dateInLong":0.0}}' \ http://localhost:8080/zstack/v1/billings/prices

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |resourceName|String|body(包含在params结构中)|资源名称| - cpu - memory - rootvolume - datavolume - snapshot

|0.6| |resourceUnit (可选)|String|body(包含在params结构中)|资源计费单元|可选值根据resourceName而定|0.6| |timeUnit|String|body(包含在params结构中)|计费时间单元| |0.6| |price|double|body(包含在params结构中)|单位价格| |0.6| |accountUuid (可选)|String|body(包含在params结构中)|账户UUID| |0.6| |dateInLong (可选)|Long|body(包含在params结构中)|长整型时刻| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "uuid": "437ade61b17e4c658844fdacfb0fc6de", "resourceName": "Volume", "resourceUnit": "1", "timeUnit": "s", "price": 2.0 } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventory|PriceInventory|详情参考inventory|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |resourceName|String|资源名称|0.6| |resourceUnit|String|资源计费单元|0.6| |timeUnit|String|计费时间单元|0.6| |price|Double|价格|0.6| |dateInLong|Long|以长整型记录的时刻|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

CreateResourcePriceAction action = new CreateResourcePriceAction(); action.resourceName = "cpu"; action.timeUnit = "s"; action.price = 100.0; action.dateInLong = 0.0; action.sessionId = "1360cf066fd547b9ae2d8f32beba717f"; CreateResourcePriceAction.Result res = action.call();

Python SDK

CreateResourcePriceAction action = CreateResourcePriceAction() action.resourceName = "cpu" action.timeUnit = "s" action.price = 100.0 action.dateInLong = 0.0 action.sessionId = "47ca95d22d8645ef8aef8dd0110cbd92" CreateResourcePriceAction.Result res = action.call()

Parent topic: 计费管理相关接口

删除资源价格(DeleteResourcePrice)

API请求

URLs

DELETE zstack/v1/billings/prices/{uuid}

Headers

OAuth: the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "OAuth: 5332b02080a141cc961457ad3b090fe4" \ -X DELETE http://localhost:8080/zstack/v1/billings/prices/a5c5bd6198824d89894cdd10969843ff

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid|String|url|资源的UUID,唯一标示该资源| |0.6| |deleteMode (可选)|String|body|删除模式| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

DeleteResourcePriceAction action = new DeleteResourcePriceAction(); action.uuid = "6a7c1ad952894d5aa2cc6b1add3062ca"; action.deleteMode = "Permissive"; action.sessionId = "e3ffecc95a5b4bcca5ce212826a14ee0"; DeleteResourcePriceAction.Result res = action.call();

Python SDK

DeleteResourcePriceAction action = DeleteResourcePriceAction() action.uuid = "14c4eef2f36e4716a279777e503ab772" action.deleteMode = "Permissive" action.sessionId = "fcbca45ec9454200b1d080b0268c17d9" DeleteResourcePriceAction.Result res = action.call()

Parent topic: 计费管理相关接口

查询资源价格(QueryResourcePrice)

API请求

URLs

GET zstack/v1/billings/prices GET zstack/v1/billing/prices/{uuid}

Headers

OAuth: the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "OAuth: 0898d6895f274f83bc9d7fe85c629fc2" \ -X GET http://localhost:8080/zstack/v1/billings/prices?q=uuid=e7a8c15058f2450dbae8a52bc3a53163

curl -H "Content-Type: application/json" \ -H "OAuth: 1e19b0c2877343e8b5cc27ba801cea5b" \ -X GET http://localhost:8080/zstack/v1/billing/prices/9b1cb8fcb98a4a77b8d1b8f5c71f3ea0

可查询字段

运行zstack-cli命令行工具,输入QueryResourcePrice并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例

{ "inventories": [ { "uuid": "127da3fe2612443187bdb5cc1c0a1b93", "resourceName": "Volume", "resourceUnit": "1", "timeUnit": "s", "price": 2.0 } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventories|List|详情参考inventories|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventories

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |resourceName|String|资源名称|0.6| |resourceUnit|String|资源计费单元|0.6| |timeUnit|String|计费时间单元|0.6| |price|Double|价格|0.6| |dateInLong|Long|以长整型记录的时刻|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

QueryResourcePriceAction action = new QueryResourcePriceAction(); action.conditions = asList("uuid=9f754355ea3147fe9e132e9e387565fc"); action.sessionId = "487ff79fdb52498ba0ebaf0825d09277"; QueryResourcePriceAction.Result res = action.call();

Python SDK

QueryResourcePriceAction action = QueryResourcePriceAction() action.conditions = ["uuid=1c26229f970f4fe599c34d56bc78b578"] action.sessionId = "30759bcfee93462eb88cf7fc88f3a364" QueryResourcePriceAction.Result res = action.call()

Parent topic: 计费管理相关接口

计算账户花费(CalculateAccountSpending)

API请求

URLs

PUT zstack/v1/billings/accounts/{accountUuid}/actions

Headers

Authorization: OAuth the-session-uuid

Body

{ "calculateAccountSpending": { "dateStart": 0.0, "dateEnd": 1.49448017929E12 }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b0422700ba91425aa234b7ad4d70e8ce" \ -X PUT -d '{"calculateAccountSpending":{"dateStart":0.0,"dateEnd":1.510669257141E12}}' \ http://localhost:8080/zstack/v1/billings/accounts/64df7cc87c583f069400e5184175d025/actions

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |accountUuid|String|body(包含在calculateAccountSpending结构中)|账户UUID| |0.6| |dateStart (可选)|Long|body(包含在calculateAccountSpending结构中)|起始日期| |0.6| |dateEnd (可选)|Long|body(包含在calculateAccountSpending结构中)|结束日期| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "total": 200.0, "spending": [ { "spending": 0.0, "details": [] } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |total|double|总额|0.6| |success|boolean|成功标志|0.6| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |spending|List|详情参考spending|0.6| |error|ErrorCode|详情参考error|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#spending

|名字|类型|描述|起始版本| |--|--|--|----| |spendingType|String|花费类型|0.6| |spending|double|花费总额|0.6| |dateStart|Long|计费起始日期|0.6| |dateEnd|Long|计费结束日期|0.6| |details|List|详情参考details|0.6|

#details

|名字|类型|描述|起始版本| |--|--|--|----| |resourceUuid|String|资源UUID|0.6| |resourceName|String|资源名称|0.6| |spending|double|花费|0.6| |type|String|类型|0.6|

SDK示例

Java SDK

CalculateAccountSpendingAction action = new CalculateAccountSpendingAction(); action.accountUuid = "b9578ee43e1745aaaddf96b2286d8055"; action.dateStart = 0.0; action.dateEnd = 1.494480179344E12; action.sessionId = "21b88c2399054090b13ac0b9fe067f75"; CalculateAccountSpendingAction.Result res = action.call();

Python SDK

CalculateAccountSpendingAction action = CalculateAccountSpendingAction() action.accountUuid = "881b1c4a85bf43f39acc29d42a9c6cd6" action.dateStart = 0.0 action.dateEnd = 1.494480179344E12 action.sessionId = "a5ae231847c14c26b62bed6e878d6c60" CalculateAccountSpendingAction.Result res = action.call()

Parent topic: 计费管理相关接口

定时器相关接口

创建定时器(CreateSchedulerTrigger)

API请求

URLs

POST zstack/v1/scheduler/triggers

Headers

Authorization: OAuth the-session-uuid

Body

{ "params": { "name": "trigger", "description": "description", "schedulerInterval": 3600.0, "repeatCount": 100.0, "startTime": 1.510669257141E12, "schedulerType": "simple" }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X POST -d '{"params":{"name":"trigger","description":"description","schedulerInterval":3600.0,"repeatCount":100.0,"startTime":1.510669257141E12,"schedulerType":"simple"}}' \ http://localhost:8080/zstack/v1/scheduler/triggers

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |name|String|body(包含在params结构中)|资源名称| |2.1| |description (可选)|String|body(包含在params结构中)|资源的详细描述| |2.1| |schedulerInterval (可选)|Integer|body(包含在params结构中)|间隔时间- 当简单定时任务执行超过一次时,必须设置间隔时间; - 简单定时任务永远重复时,必须设置间隔时间

| |2.1| |repeatCount (可选)|Integer|body(包含在params结构中)| | |2.1| |startTime (可选)|Long|body(包含在params结构中)|Unix Time| |2.1| |schedulerType|String|body(包含在params结构中)| - simple - cron

| |2.1| |cron (可选)|String|body(包含在params结构中)| | |2.1| |resourceUuid (可选)|String|body(包含在params结构中)| | |2.1| |systemTags (可选)|List|body| | |2.1| |userTags (可选)|List|body| | |2.1|

API返回

返回示例

{ "inventory": { "uuid": "20c7355021f83597a4cf7854f5788b74", "name": "trigger", "description": "this is a scheduler trigger", "createDate": "Nov 14, 2017 10:20:57 PM", "lastOpDate": "Nov 14, 2017 10:20:57 PM" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|2.1| |inventory|SchedulerTriggerInventory|详情参考inventory|2.1|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|2.1| |description|String|错误的概要描述|2.1| |details|String|错误的详细信息|2.1| |elaboration|String|保留字段,默认为null|2.1| |opaque|LinkedHashMap|保留字段,默认为null|2.1| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|2.1|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|2.1| |name|String|资源名称|2.1| |description|String|资源的详细描述|2.1| |schedulerType|String| |2.1| |schedulerInterval|Integer| |2.1| |repeatCount|Integer| |2.1| |startTime|Timestamp| |2.1| |stopTime|Timestamp| |2.1| |createDate|Timestamp|创建时间|2.1| |lastOpDate|Timestamp|最后一次修改时间|2.1| |jobsUuid|List| |2.1|

SDK示例

Java SDK

CreateSchedulerTriggerAction action = new CreateSchedulerTriggerAction(); action.name = "scheduler trigger"; action.schedulerInterval = 1000.0; action.repeatCount = 10.0; action.startTime = 1.500257934165E12; action.schedulerType = "simple"; action.sessionId = "412d5e5ffaa247c89864f32715c1ae82"; CreateSchedulerTriggerAction.Result res = action.call();

Python SDK

CreateSchedulerTriggerAction action = CreateSchedulerTriggerAction() action.name = "scheduler trigger" action.schedulerInterval = 1000.0 action.repeatCount = 10.0 action.startTime = 1.500257934177E12 action.schedulerType = "simple" action.sessionId = "89bc45d795df44688c7ad4bba232490f" CreateSchedulerTriggerAction.Result res = action.call()

Parent topic: 定时器相关接口

删除定时器(DeleleSchedulerTrigger)

API请求

URLs

DELETE zstack/v1/scheduler/triggers/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 9101c6e1eef94f2aa7b76ce2833c3991" \ -X DELETE http://localhost:8080/zstack/v1/scheduler/triggers/fe26ab519ac24389bae2664503258590?

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid|String|url|资源的UUID,唯一标示该资源| |2.1| |deleteMode (可选)|String|body| | |2.1| |systemTags (可选)|List|body| | |2.1| |userTags (可选)|List|body| | |2.1|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

DeleteSchedulerTriggerAction action = new DeleteSchedulerTriggerAction(); action.uuid = "3ac4a7a8d71f4147b98a59995cbcf807"; action.deleteMode = "Permissive"; action.sessionId = "c0de81361fb743c297aec4f4f35085b9"; DeleteSchedulerTriggerAction.Result res = action.call();

Python SDK

DeleteSchedulerTriggerAction action = DeleteSchedulerTriggerAction() action.uuid = "769b16c91f234f2c8e2fc4fe6fe8441b" action.deleteMode = "Permissive" action.sessionId = "a960f5dfa4304cd1bcb96ed0d16c3e67" DeleteSchedulerTriggerAction.Result res = action.call()

Parent topic: 定时器相关接口

查询定时器(QuerySchedulerTrigger)

API请求

URLs

GET zstack/v1/scheduler/triggers GET zstack/v1/scheduler/triggers/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth f86c2715690e402c85aec6d981d1d9b1" \ -X GET http://localhost:8080/zstack/v1/scheduler/triggers?q=name=TestSchedulerTrigger&q=name=trigger

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth bb395f07706c4e5f93fb9d767248001e" \ -X GET http://localhost:8080/zstack/v1/scheduler/triggers/245751f5233d4bc3b4a9966e8cdd0e7e

可查询字段

运行zstack-cli命令行工具,输入QuerySchedulerTrigger并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例

{ "inventories": [ { "uuid": "8bc53f2626f14f5a974300909e4229f3", "name": "test", "description": "a test trigger", "startTime": "Jul 17, 2017 10:18:54 AM", "stopTime": "Jul 17, 2017 10:18:54 AM", "createDate": "Jul 17, 2017 10:18:54 AM", "lastOpDate": "Jul 17, 2017 10:18:54 AM" } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|2.1| |inventories|List|详情参考inventories|2.1|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|2.1| |description|String|错误的概要描述|2.1| |details|String|错误的详细信息|2.1| |elaboration|String|保留字段,默认为null|2.1| |opaque|LinkedHashMap|保留字段,默认为null|2.1| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|2.1|

#inventories

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |name|String|资源名称|0.6| |description|String|资源的详细描述|0.6| |schedulerType|String| |0.6| |schedulerInterval|Integer| |0.6| |repeatCount|Integer| |0.6| |startTime|Timestamp| |0.6| |stopTime|Timestamp| |0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6| |jobsUuid|List| |0.6|

SDK示例

Java SDK

QuerySchedulerTriggerAction action = new QuerySchedulerTriggerAction(); action.conditions = asList("name=TestSchedulerTrigger","name=trigger"); action.sessionId = "fd4f6b37415e467b847e862e2d003639"; QuerySchedulerTriggerAction.Result res = action.call();

Python SDK

QuerySchedulerTriggerAction action = QuerySchedulerTriggerAction() action.conditions = ["name=TestSchedulerTrigger","name=trigger"] action.sessionId = "d1353798888548bd87fb76a0b431ad3f" QuerySchedulerTriggerAction.Result res = action.call()

Parent topic: 定时器相关接口

更新定时器(UpdateSchedulerTrigger)

API请求

URLs

PUT zstack/v1/scheduler/triggers/{uuid}/actions

Headers

Authorization: OAuth the-session-uuid

Body

{ "updateSchedulerTrigger": { "name": "Test2", "description": "new test", "schedulerInterval": 3600.0, "repeatCount": 100.0, "startTime": 1.510669257141E12 }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X PUT -d '{"updateSchedulerTrigger":{"name":"Test2","description":"new test","schedulerInterval":3600.0,"repeatCount":100.0,"startTime":1.510669257141E12}}' \ http://localhost:8080/zstack/v1/scheduler/triggers/029825497836308c8ab6146e57015c20/actions

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid|String|url|资源的UUID,唯一标示该资源| |2.1| |name (可选)|String|body(包含在updateSchedulerTrigger结构中)|资源名称| |2.1| |description (可选)|String|body(包含在updateSchedulerTrigger结构中)|资源的详细描述| |2.1| |schedulerInterval (可选)|Integer|body(包含在updateSchedulerTrigger结构中)| | |2.3| |repeatCount (可选)|Integer|body(包含在updateSchedulerTrigger结构中)| | |2.3| |startTime (可选)|Long|body(包含在updateSchedulerTrigger结构中)| | |2.3| |cron (可选)|String|body(包含在updateSchedulerTrigger结构中)| | |2.3| |systemTags (可选)|List|body| | |2.1| |userTags (可选)|List|body| | |2.1|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

UpdateSchedulerTriggerAction action = new UpdateSchedulerTriggerAction(); action.uuid = "2b18c3e0f3f1428e97dbd90badd54211"; action.name = "Test2"; action.description = "new test"; action.schedulerInterval = 3600.0; action.repeatCount = 100.0; action.startTime = 1.510669257141E12; action.sessionId = "f0a41bd750b64bf09ed7122c1b9f4949"; UpdateSchedulerTriggerAction.Result res = action.call();

Python SDK

UpdateSchedulerTriggerAction action = UpdateSchedulerTriggerAction() action.uuid = "3e077605d62e4075be62cb1218c7762f" action.name = "Test2" action.description = "new test" action.schedulerInterval = 3600.0; action.repeatCount = 100.0; action.startTime = 1.510669257141E12; action.sessionId = "f9133e066bbe4190a8ba5b2acb038669" UpdateSchedulerTriggerAction.Result res = action.call()

Parent topic: 定时器相关接口

添加定时任务到定时器(AddSchedulerJobToSchedulerTrigger)

API请求

URLs

POST zstack/v1/scheduler/jobs/{schedulerJobUuid}/scheduler/triggers/{schedulerTriggerUuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X POST http://localhost:8080/zstack/v1/scheduler/jobs/0bae2d859dfa3863bc3e02f20bbce8a5/scheduler/triggers/3653b5151ed032178264edaaf9e8c3d1

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |schedulerJobUuid|String|url|定时任务UUID| |2.1| |schedulerTriggerUuid|String|url|定时器UUID| |2.1| |systemTags (可选)|List|body| | |2.1| |userTags (可选)|List|body| | |2.1|

API返回

返回示例

{ "inventory": { "uuid": "ceb4e1ee7e204505917387f0582f1710", "schedulerJobUuid": "7352a98748f548ed974492ac8cc5172a", "schedulerTriggerUuid": "21960244adbc427098bb37c31709ffbe" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|2.1| |inventory|SchedulerJobSchedulerTriggerInventory|详情参考inventory|2.1|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|2.1| |description|String|错误的概要描述|2.1| |details|String|错误的详细信息|2.1| |elaboration|String|保留字段,默认为null|2.1| |opaque|LinkedHashMap|保留字段,默认为null|2.1| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|2.1|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|2.1| |schedulerJobUuid|String| |2.1| |schedulerTriggerUuid|String| |2.1| |jobGroup|String| |2.1| |triggerGroup|String| |2.1| |createDate|Timestamp|创建时间|2.1| |lastOpDate|Timestamp|最后一次修改时间|2.1|

SDK示例

Java SDK

AddSchedulerJobToSchedulerTriggerAction action = new AddSchedulerJobToSchedulerTriggerAction(); action.schedulerJobUuid = "7105d412a37c4bef8321ca54061e1949"; action.schedulerTriggerUuid = "a8d4778d455948648f3abb36c968e88a"; action.sessionId = "554ea7d4857b49e8a8fc0e1bb7bb3333"; AddSchedulerJobToSchedulerTriggerAction.Result res = action.call();

Python SDK

AddSchedulerJobToSchedulerTriggerAction action = AddSchedulerJobToSchedulerTriggerAction() action.schedulerJobUuid = "363d635aca674058a34bc7b7621934d9" action.schedulerTriggerUuid = "7d5e4ba74efb428c81c668b5c5c1be92" action.sessionId = "33383cc0e7fb49b583e6b3d25c76006b" AddSchedulerJobToSchedulerTriggerAction.Result res = action.call()

Parent topic: 定时器相关接口

从定时器移除定时任务(RemoveSchedulerJobFromSchedulerTrigger)

API请求

URLs

DELETE zstack/v1/scheduler/jobs/{schedulerJobUuid}/scheduler/triggers/{schedulerTriggerUuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 32b614664dfc4c77a4ced15b7b434f2b" \ -X DELETE http://localhost:8080/zstack/v1/scheduler/jobs/62af314ef99046f8929934e0e9b41892/scheduler/triggers/fe1c048505c54cb3b27981fc2e967770?

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |schedulerJobUuid|String|url|定时任务UUID| |2.1| |schedulerTriggerUuid|String|url|定时器UUID| |2.1| |systemTags (可选)|List|body| | |2.1| |userTags (可选)|List|body| | |2.1|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

RemoveSchedulerJobFromSchedulerTriggerAction action = new RemoveSchedulerJobFromSchedulerTriggerAction(); action.schedulerJobUuid = "9fe2e6e2059c4034b41e8a9422eff40f"; action.schedulerTriggerUuid = "3e8934f791f04ebcaeb4523a10ae020a"; action.sessionId = "2754c780ce3746b88045b11124c7cd71"; RemoveSchedulerJobFromSchedulerTriggerAction.Result res = action.call();

Python SDK

RemoveSchedulerJobFromSchedulerTriggerAction action = RemoveSchedulerJobFromSchedulerTriggerAction() action.schedulerJobUuid = "18041254de834d398897ae66197db7c1" action.schedulerTriggerUuid = "a7f89b17034a4714ba3ecda2435aa5a0" action.sessionId = "7944081646ef439a9e5847380491e998" RemoveSchedulerJobFromSchedulerTriggerAction.Result res = action.call()

Parent topic: 定时器相关接口

创建定时任务(CreateSchedulerJob)

API请求

URLs

POST zstack/v1/scheduler/jobs

Headers

Authorization: OAuth the-session-uuid

Body

{ "params": { "name": "scheduler job", "targetResourceUuid": "9c9e9ce0aa824137a0944daa4127355d", "type": "startVm" }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X PUT -d '{"changeSchedulerState":{"stateEvent":"disable"}}' \ http://localhost:8080/zstack/v1/schedulers/53cd804df69d3565b4efcd460c0ddd52

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid|String|url|资源的UUID,唯一标示该资源| |2.1| |stateEvent|String|body(包含在changeSchedulerState结构中)|要设置的定时任务状态| - enable - disable

|2.1| |systemTags (可选)|List|body|系统标签| |2.1| |userTags (可选)|List|body|用户标签| |2.1|

API返回

返回示例:

{ "inventory": { "uuid": "07a35fc1199d31c9bca5db5334f947c9", "targetResourceUuid": "5d07512a1bf036e7be1e8938ff7938b3", "name": "Test", "description": "Create volume snapshot scheduler job", "createDate": "Nov 14, 2017 10:20:57 PM", "lastOpDate": "Nov 14, 2017 10:20:57 PM" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|2.1| |inventory|SchedulerInventory|详情参考inventory|2.1|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|2.1| |description|String|错误的概要描述|2.1| |details|String|错误的详细信息|2.1| |elaboration|String|保留字段,默认为null|2.1| |opaque|LinkedHashMap|保留字段,默认为null|2.1| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|2.1|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|2.1| |targetResourceUuid|String| |2.1| |name|String|资源名称|2.1| |description|String|资源的详细描述|2.1| |state|String| |2.1| |createDate|Timestamp|创建时间|2.1| |lastOpDate|Timestamp|最后一次修改时间|2.1| |triggersUuid|List| |2.1|

SDK示例

Java SDK

ChangeSchedulerStateAction action = new ChangeSchedulerStateAction(); action.uuid = "53cd804df69d3565b4efcd460c0ddd52"; action.stateEvent = "disable"; action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"; ChangeSchedulerStateAction.Result res = action.call();

Python SDK

ChangeSchedulerStateAction action = ChangeSchedulerStateAction() action.uuid = "53cd804df69d3565b4efcd460c0ddd52" action.stateEvent = "disable" action.sessionId = "b86c9016b4f24953a9edefb53ca0678c" ChangeSchedulerStateAction.Result res = action.call()

Parent topic: 定时器相关接口

删除定时任务(DeleteSchedulerJob)

API请求

URLs

DELETE zstack/v1/scheduler/jobs/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth c9b798cf05f44047b9f79f4f66e0e960" \ -X DELETE http://localhost:8080/zstack/v1/scheduler/jobs/1ae34aa114424c45ab5af9f9be7af8c1?

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid|String|url|资源的UUID,唯一标示该资源| |2.1| |deleteMode (可选)|String|body| | |2.1| |systemTags (可选)|List|body| | |2.1| |userTags (可选)|List|body| | |2.1|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

DeleteSchedulerJobAction action = new DeleteSchedulerJobAction(); action.uuid = "8730c7093939498c9bea46f84435cced"; action.deleteMode = "Permissive"; action.sessionId = "be23055450334fb9add5e0e9031cf238"; DeleteSchedulerJobAction.Result res = action.call();

Python SDK

DeleteSchedulerJobAction action = DeleteSchedulerJobAction() action.uuid = "8a723f909a94473fab6cfb41fb34077f" action.deleteMode = "Permissive" action.sessionId = "4e0af23135a7446b90fe40c911f5e946" DeleteSchedulerJobAction.Result res = action.call()

Parent topic: 定时器相关接口

查询定时任务(QuerySchedulerJob)

API请求

URLs

GET zstack/v1/scheduler/jobs GET zstack/v1/scheduler/jobs/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b0d89c0878b3492b9f258fcadc81e5f2" \ -X GET http://localhost:8080/zstack/v1/scheduler/jobs?q=name=TestScheduler&q=state=Enabled

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth c50c86041f044014bfdc88f2806d989b" \ -X GET http://localhost:8080/zstack/v1/scheduler/jobs/eb52cb8434bc4929b34097d630043695

可查询字段

运行zstack-cli命令行工具,输入QuerySchedulerJob并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例

{ "inventories": [ { "uuid": "346e89a1e0f64ce092fc4541f695151f", "targetResourceUuid": "b08f45dbea734a9b9507bb773af28428", "name": "test", "createDate": "Jul 17, 2017 10:18:54 AM", "lastOpDate": "Jul 17, 2017 10:18:54 AM" } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|2.1| |inventories|List|详情参考inventories|2.1|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|2.1| |description|String|错误的概要描述|2.1| |details|String|错误的详细信息|2.1| |elaboration|String|保留字段,默认为null|2.1| |opaque|LinkedHashMap|保留字段,默认为null|2.1| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|2.1|

#inventories

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|2.1| |targetResourceUuid|String| |2.1| |name|String|资源名称|2.1| |description|String|资源的详细描述|2.1| |state|String| |2.1| |createDate|Timestamp|创建时间|2.1| |lastOpDate|Timestamp|最后一次修改时间|2.1| |triggersUuid|List| |2.1|

SDK示例

Java SDK

QuerySchedulerJobAction action = new QuerySchedulerJobAction(); action.conditions = asList("name=TestScheduler","state=Enabled"); action.sessionId = "0864c676a4fc4e408dc6d89548e1387f"; QuerySchedulerJobAction.Result res = action.call();

Python SDK

QuerySchedulerJobAction action = QuerySchedulerJobAction() action.conditions = ["name=TestScheduler","state=Enabled"] action.sessionId = "a25af40af81541c5b7160af8a135b040" QuerySchedulerJobAction.Result res = action.call()

Parent topic: 定时器相关接口

更新定时任务(UpdateSchedulerJob)

API请求

URLs

PUT zstack/v1/scheduler/jobs/{uuid}/actions

Headers

Authorization: OAuth the-session-uuid

Body

{ "updateSchedulerJob": { "name": "Test2", "description": "new test" }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X PUT -d '{"updateSchedulerJob":{"name":"Test2","description":"new test"}}' \ http://localhost:8080/zstack/v1/scheduler/jobs/676b5d17ee953aa892c6439a06e49bf6/actions

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid|String|url|资源的UUID,唯一标示该资源| |2.1| |name (可选)|String|body(包含在updateSchedulerJob结构中)|资源名称| |2.1| |description (可选)|String|body(包含在updateSchedulerJob结构中)|资源的详细描述| |2.1| |systemTags (可选)|List|body| | |2.1| |userTags (可选)|List|body| | |2.1|

API返回

返回示例

{ "inventory": { "uuid": "11f1249eaae74b50b909839492ee0991", "targetResourceUuid": "eee374cb49904855ad1c46a1c92846af", "name": "Test", "description": "create volume snapshot job", "createDate": "Jul 17, 2017 10:18:53 AM", "lastOpDate": "Jul 17, 2017 10:18:53 AM" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|2.1| |inventory|SchedulerJobInventory|详情参考inventory|2.1|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|2.1| |description|String|错误的概要描述|2.1| |details|String|错误的详细信息|2.1| |elaboration|String|保留字段,默认为null|2.1| |opaque|LinkedHashMap|保留字段,默认为null|2.1| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|2.1|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|2.1| |targetResourceUuid|String| |2.1| |name|String|资源名称|2.1| |description|String|资源的详细描述|2.1| |state|String| |2.1| |createDate|Timestamp|创建时间|2.1| |lastOpDate|Timestamp|最后一次修改时间|2.1| |triggersUuid|List| |2.1|

SDK示例

Java SDK

UpdateSchedulerJobAction action = new UpdateSchedulerJobAction(); action.uuid = "4283a6a09fac4871ab8cd4f94384d32e"; action.name = "Test2"; action.description = "new test"; action.sessionId = "c15d0314892e493281494181e19eae02"; UpdateSchedulerJobAction.Result res = action.call();

Python SDK

UpdateSchedulerJobAction action = UpdateSchedulerJobAction() action.uuid = "f0696f10eb5b408b8f6fddb1094f7b2b" action.name = "Test2" action.description = "new test" action.sessionId = "47041d647e834f5698e613a5e4a99a08" UpdateSchedulerJobAction.Result res = action.call()

Parent topic: 定时器相关接口

获取未挂载定时器的任务(GetNoTriggerSchedulerJobs)

API请求

URLs

GET zstack/v1/scheduler/jobs/candidates

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X GET http://localhost:8080/zstack/v1/scheduler/jobs/candidates

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |systemTags (可选)|List|query| | |0.6| |userTags (可选)|List|query| | |0.6|

API返回

返回示例

{ "inventories": [ { "uuid": "49e45562c0db49aa87a5bb7b3945d815", "name": "job", "description": "this is a scheduler job", "createDate": "Nov 14, 2017 10:20:57 PM", "lastOpDate": "Nov 14, 2017 10:20:57 PM" } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventories|List|详情参考inventories|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventories

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |targetResourceUuid|String| |0.6| |name|String|资源名称|0.6| |description|String|资源的详细描述|0.6| |state|String| |0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6| |triggersUuid|List| |0.6|

SDK示例

Java SDK

GetNoTriggerSchedulerJobsAction action = new GetNoTriggerSchedulerJobsAction(); action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"; GetNoTriggerSchedulerJobsAction.Result res = action.call();

Python SDK

GetNoTriggerSchedulerJobsAction action = GetNoTriggerSchedulerJobsAction() action.sessionId = "b86c9016b4f24953a9edefb53ca0678c" GetNoTriggerSchedulerJobsAction.Result res = action.call()

Parent topic: 定时器相关接口

改变定时任务状态(ChangeSchedulerState)

API请求

URLs

PUT zstack/v1/schedulers/{uuid}

Headers

Authorization: OAuth the-session-uuid

Body

{ "changeSchedulerState": { "stateEvent": "disable" }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X PUT -d '{"changeSchedulerState":{"stateEvent":"disable"}}' \ http://localhost:8080/zstack/v1/schedulers/53cd804df69d3565b4efcd460c0ddd52

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid|String|url|资源的UUID,唯一标示该资源| |2.1| |stateEvent|String|body(包含在changeSchedulerState结构中)|要设置的定时任务状态| - enable - disable

|2.1| |systemTags (可选)|List|body|系统标签| |2.1| |userTags (可选)|List|body|用户标签| |2.1|

API返回

返回示例

{ "inventory": { "uuid": "07a35fc1199d31c9bca5db5334f947c9", "targetResourceUuid": "5d07512a1bf036e7be1e8938ff7938b3", "name": "Test", "description": "Create volume snapshot scheduler job", "createDate": "Nov 14, 2017 10:20:57 PM", "lastOpDate": "Nov 14, 2017 10:20:57 PM" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|2.1| |inventory|SchedulerInventory|详情参考inventory|2.1|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|2.1| |description|String|错误的概要描述|2.1| |details|String|错误的详细信息|2.1| |elaboration|String|保留字段,默认为null|2.1| |opaque|LinkedHashMap|保留字段,默认为null|2.1| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|2.1|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|2.1| |targetResourceUuid|String| |2.1| |name|String|资源名称|2.1| |description|String|资源的详细描述|2.1| |state|String| |2.1| |createDate|Timestamp|创建时间|2.1| |lastOpDate|Timestamp|最后一次修改时间|2.1| |triggersUuid|List| |2.1|

SDK示例

Java SDK

ChangeSchedulerStateAction action = new ChangeSchedulerStateAction(); action.uuid = "53cd804df69d3565b4efcd460c0ddd52"; action.stateEvent = "disable"; action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"; ChangeSchedulerStateAction.Result res = action.call();

Python SDK

ChangeSchedulerStateAction action = ChangeSchedulerStateAction() action.uuid = "53cd804df69d3565b4efcd460c0ddd52" action.stateEvent = "disable" action.sessionId = "b86c9016b4f24953a9edefb53ca0678c" ChangeSchedulerStateAction.Result res = action.call()

Parent topic: 定时器相关接口

AD/LDAP相关接口

添加AD/LDAP服务器(AddLdapServer)

API请求

URLs

POST zstack/v1/ldap/servers

Headers

Authorization: OAuth the-session-uuid

Body

{ "params": { "name": "miao", "description": "miao desc", "url": "ldap://localhost:1888", "base": "dc\u003dexample,dc\u003dcom", "username": "", "password": "", "encryption": "None" }, "systemTags": [], "userTags": [] }

上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X POST -d '{"params":{"name":"miao","description":"miao desc","url":"ldap://localhost:1888","base":"dc\u003dexample,dc\u003dcom","username":"","password":"","encryption":"None"}}' \ http://localhost:8080/zstack/v1/ldap/servers

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |name|String|body(包含在params结构中)|资源名称| |0.6| |description|String|body(包含在params结构中)|资源的详细描述| |0.6| |url|String|body(包含在params结构中)|LDAP服务器访问地址| |0.6| |base|String|body(包含在params结构中)|LDAP服务查询BaseDN| |0.6| |username|String|body(包含在params结构中)|访问LDAP服务器使用的用户名| |0.6| |password|String|body(包含在params结构中)|密码| |0.6| |encryption|String|body(包含在params结构中)|加密方式| - None - TLS

|0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "uuid": "ef7291bd94ce478880938851e3ff6ad6", "name": "miao", "description": "miao desc", "url": "ldap://localhost:1888", "base": "dc\u003dexample,dc\u003dcom", "username": "", "password": "", "encryption": "None" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventory|LdapServerInventory|详情参考inventory|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |name|String|资源名称|0.6| |description|String|资源的详细描述|0.6| |url|String| |0.6| |base|String|LDAP服务器访问地址|0.6| |username|String|用于访问LDAP服务器的用户名|0.6| |password|String|密码|0.6| |encryption|String|加密方式|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

AddLdapServerAction action = new AddLdapServerAction(); action.name = "miao"; action.description = "miao desc"; action.url = "ldap://localhost:1888"; action.base = "dc=example,dc=com"; action.username = ""; action.password = ""; action.encryption = "None"; action.sessionId = "c805609607b94f1688e4f5791089ab6f"; AddLdapServerAction.Result res = action.call();

Python SDK

AddLdapServerAction action = AddLdapServerAction() action.name = "miao" action.description = "miao desc" action.url = "ldap://localhost:1888" action.base = "dc=example,dc=com" action.username = "" action.password = "" action.encryption = "None" action.sessionId = "611a70f771874450945f77465bca7642" AddLdapServerAction.Result res = action.call()

Parent topic: AD/LDAP相关接口

删除AD/LDAP服务器(DeleteLdapServer)

API请求

URLs

DELETE/v1/ldap/servers/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth a90abb1116c0428097769adfdc9ae867" \ -X DELETE http://localhost:8080/zstack/v1/ldap/servers/93d7c467c493464fa3d244163c94f64e?

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid|String|url|资源的UUID,唯一标示该资源| |0.6| |deleteMode (可选)|String|body|删除模式| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

DeleteLdapServerAction action = new DeleteLdapServerAction(); action.uuid = "0e757aebf26346c19ee1f163ea9f0915"; action.deleteMode = "Permissive"; action.sessionId = "3dae39cdbba749ba91deda6b854695ec"; DeleteLdapServerAction.Result res = action.call();

Python SDK

DeleteLdapServerAction action = DeleteLdapServerAction() action.uuid = "7755f302acd44c62833f9d4eb3f7327c" action.deleteMode = "Permissive" action.sessionId = "61e33f5ab13b44ef873ef7fc719d3804" DeleteLdapServerAction.Result res = action.call()

Parent topic: AD/LDAP相关接口

查询AD/LDAP服务器(QueryLdapServer)

API请求

URLs

GET zstack/v1/ldap/servers GET zstack/v1/ldap/servers/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 940b9dba281d40b897497a95e8a0e942" \ -X GET http://localhost:8080/zstack/v1/ldap/servers?q=name=ldap server

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth e4e74e66dc074b24b7071b43b12240a2" \ -X GET http://localhost:8080/zstack/v1/ldap/servers/c898d74cdcb94ac4b3b28ac6b7a8f7f5

可查询字段zstack-cli

运行命令行工具,输入QueryLdapServer并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例

{ "inventories": [ { "uuid": "91820f68407a441c9ba031ac15fa322d", "name": "miao", "description": "miao desc", "url": "ldap://localhost:1888", "base": "dc\u003dexample,dc\u003dcom", "username": "", "password": "", "encryption": "None" } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventories|List|详情参考inventories|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventories

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |name|String|资源名称|0.6| |description|String|资源的详细描述|0.6| |url|String| |0.6| |base|String|LDAP服务器访问地址|0.6| |username|String|用于访问LDAP服务器的用户名|0.6| |password|String|密码|0.6| |encryption|String|加密方式|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

QueryLdapServerAction action = new QueryLdapServerAction(); action.conditions = asList("name=ldap server"); action.sessionId = "a8d28261d5b940c9bdd4712a511bd537"; QueryLdapServerAction.Result res = action.call();

Python SDK

QueryLdapServerAction action = QueryLdapServerAction() action.conditions = ["name=ldap server"] action.sessionId = "aee6bc43a2fb4f1eb6c35e3a064dd464" QueryLdapServerAction.Result res = action.call()

Parent topic: AD/LDAP相关接口

更新AD/LDAP服务器(UpdateLdapServer)

API请求

URLs

PUT zstack/v1/ldap/servers/{ldapServerUuid}

Headers

Authorization: OAuth the-session-uuid

Body

{ "updateLdapServer": { "name": "new name" }, "systemTags": [], "userTags": [] }

上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth e0360b3fd1d04df0b98005ab41f233ea" \ -X PUT -d '{"updateLdapServer":{"name":"new name"}}' \ http://localhost:8080/zstack/v1/ldap/servers/6c2af8cab16b3310a3d31aa772b093ba

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |ldapServerUuid|String|url|LDAP服务器的UUID| |0.6| |name (可选)|String|body(包含在updateLdapServer结构中)|资源名称| |0.6| |description (可选)|String|body(包含在updateLdapServer结构中)|资源的详细描述| |0.6| |url (可选)|String|body(包含在updateLdapServer结构中)|LDAP服务器的访问地址| |0.6| |base (可选)|String|body(包含在updateLdapServer结构中)|LDAP服务器的查询BaseDN| |0.6| |username (可选)|String|body(包含在updateLdapServer结构中)|访问LDAP服务器的用户名| |0.6| |password (可选)|String|body(包含在updateLdapServer结构中)|密码| |0.6| |encryption (可选)|String|body(包含在updateLdapServer结构中)|加密方式| - None - TLS

|0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "uuid": "8e1ee5b25564449fbd6054621567b5c1", "name": "new name", "description": "miao desc", "url": "ldap://localhost:1888", "base": "dc\u003dexample,dc\u003dcom", "username": "", "password": "", "encryption": "None" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventory|LdapServerInventory|详情参考inventory|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |name|String|资源名称|0.6| |description|String|资源的详细描述|0.6| |url|String| |0.6| |base|String|LDAP服务器访问地址|0.6| |username|String|用于访问LDAP服务器的用户名|0.6| |password|String|密码|0.6| |encryption|String|加密方式|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

UpdateLdapServerAction action = new UpdateLdapServerAction(); action.ldapServerUuid = "37fbaf59c5d74dd7b61c2af4e74c28cf"; action.name = "new name"; action.sessionId = "f968929105af41ef8a6a2c602f315c91"; UpdateLdapServerAction.Result res = action.call();

Python SDK

UpdateLdapServerAction action = UpdateLdapServerAction() action.ldapServerUuid = "57e7fe86092046228999e8599c6c8bd1" action.name = "new name" action.sessionId = "f6ca4878b0164e9eab1d6219777c5af2" UpdateLdapServerAction.Result res = action.call()

Parent topic: AD/LDAP相关接口

创建AD/LDAP绑定(CreateLdapBinding)

API请求

URLs

POST zstack/v1/ldap/bindings

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth fcb22308a60b4017bb556799a7f735c7" \ -X POST http://localhost:8080/zstack/v1/ldap/bindings

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |ldapUid|String|body|LDAP UID| |0.6| |accountUuid|String|body|账户UUID| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "uuid": "a552eb007adf4070ade72a4b678ecc30", "ldapUid": "ou\u003dEmployee,uid\u003dtest", "ldapServerUuid": "cd37f226e18c4ef09bb613200e3e90ba", "accountUuid": "5ff96c17eb8f476a988991e9410b153f" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。详情参考error|0.6| |inventory|LdapAccountRefInventory|详情参考inventory|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |ldapUid|String|LDAP登录使用的UID|0.6| |ldapServerUuid|String|LDAP服务器UUID|0.6| |accountUuid|String|账户UUID|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

CreateLdapBindingAction action = new CreateLdapBindingAction(); action.ldapUid = "ou=Employee,uid=test"; action.accountUuid = "7bff0855d3da4ab89659d29821d6daee"; action.sessionId = "5fd897a8db504aee91a64a3b02c05ce9"; CreateLdapBindingAction.Result res = action.call();

Python SDK

CreateLdapBindingAction action = CreateLdapBindingAction() action.ldapUid = "ou=Employee,uid=test" action.accountUuid = "db2842e0b16d4aa2af39abee7e80d2f1" action.sessionId = "9ece25398fe74a91a90cec68b50cd203" CreateLdapBindingAction.Result res = action.call()

Parent topic: AD/LDAP相关接口

删除AD/LDAP绑定(DeleteLdapBinding)

API请求

URLs

DELETE/v1/ldap/bindings/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 50d8d41e03b54adf9d8d88342a9d6efe" \ -X DELETE http://localhost:8080/zstack/v1/ldap/bindings/9a04287ade54400686e99485c86d9545?

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid|String|url|资源的UUID,唯一标示该资源| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

该API成功时返回一个空的JSON结构{},出错时返回的JSON结构包含一个error字段,例如:

{ "error": { "code": "SYS.1001", "description": "A message or a operation timeout", "details": "Create VM on KVM timeout after 300s" } }

SDK示例

Java SDK

DeleteLdapBindingAction action = new DeleteLdapBindingAction(); action.uuid = "5f9ff578f8ff4231b2ad18f5aa185076"; action.sessionId = "6690dcc7a9c64c26a17ae9bf29955e0a"; DeleteLdapBindingAction.Result res = action.call();

Python SDK

DeleteLdapBindingAction action = DeleteLdapBindingAction() action.uuid = "3e5a338390d046008e2723c475c90a66" action.sessionId = "2f93ee0fc083464fbe73053354ba470c" DeleteLdapBindingAction.Result res = action.call()

Parent topic: AD/LDAP相关接口

查询AD/LDAP绑定(QueryLdapBinding)

API请求

URLs

GET zstack/v1/ldap/bindings GET zstack/v1/ldap/bindings/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth f114b38ccae244c38cda7ec7dbdd062c" \ -X GET http://localhost:8080/zstack/v1/ldap/bindings?q=accountUuid=f1672bbe810b4b3b89f030f5f51fdb79

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 43f9144da747462eaa08da071d317c45" \ -X GET http://localhost:8080/zstack/v1/ldap/bindings/9e959125b2f64a86a2a380b335b2543e

可查询字段

运行zstack-cli命令行工具,输入QueryLdapBinding并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例

{ "inventories": [ { "uuid": "7e7c5818d2bc4d45b61fdbed5c1a64b0", "ldapUid": "ou\u003dEmployee,uid\u003dtest", "ldapServerUuid": "540e7691df7349c58cff8ffcaf305b9b", "accountUuid": "0829b88f337b4500b2ba28936fe5ae3d" } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventories|List|详情参考inventories|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述5|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventories

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |ldapUid|String|LDAP登录使用的UID|0.6| |ldapServerUuid|String|LDAP服务器UUID|0.6| |accountUuid|String|账户UUID|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

QueryLdapBindingAction action = new QueryLdapBindingAction(); action.conditions = asList("accountUuid=d5915883c1c04b62af8423f04bb1b3f3"); action.sessionId = "2b7a31a70f7d4e90b0159cd0b9396f26"; QueryLdapBindingAction.Result res = action.call();

Python SDK

QueryLdapBindingAction action = QueryLdapBindingAction() action.conditions = ["accountUuid=15cdbd6f45bf434492ef22eb2d77b6f4"] action.sessionId = "4956fb9e5d874e88851634154bda4d4a" QueryLdapBindingAction.Result res = action.call()

Parent topic: AD/LDAP相关接口

清理无效的AD/LDAP绑定(CleanInvalidLdapBinding)

API请求

URLs

PUT zstack/v1/ldap/bindings/actions

Headers

Authorization: OAuth the-session-uuid

Body

{ "cleanInvalidLdapBinding": {}, "systemTags": [], "userTags": [] }

上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth f8ba3bdbb1fe407db3da890e5a47d322" \ -X PUT -d '{"cleanInvalidLdapBinding":{}}' \ http://localhost:8080/zstack/v1/ldap/bindings/actions

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventories": [ { "uuid": "f9e03ca4fe8a3680831df56460533615", "name": "admin", "type": "Normal", "createDate": "Nov 14, 2017 10:20:57 PM", "lastOpDate": "Nov 14, 2017 10:20:57 PM" } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventories|List|详情参考inventories|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventories

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |name|String|资源名称|0.6| |description|String|资源的详细描述|0.6| |type|String|账户类型(管理员,普通账户)|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

CleanInvalidLdapBindingAction action = new CleanInvalidLdapBindingAction(); action.sessionId = "ba374e312f0044669323e3ba55aa44a2"; CleanInvalidLdapBindingAction.Result res = action.call();

Python SDK

CleanInvalidLdapBindingAction action = CleanInvalidLdapBindingAction() action.sessionId = "61a940c24a5e4667a03c87dbd968dfd8" CleanInvalidLdapBindingAction.Result res = action.call()

Parent topic: AD/LDAP相关接口

使用AD/LDAP身份登录(LogInByLdap)

API请求

URLs

PUT zstack/v1/ldap/login

Body

{ "logInByLdap": { "uid": "ou\u003dEmployee,uid\u003dtest", "password": "password" }, "systemTags": [], "userTags": [] }

上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -X PUT -d '{"logInByLdap":{"uid":"ou\u003dEmployee,uid\u003dtest","password":"password"}}' \ http://localhost:8080/zstack/v1/ldap/login

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uid|String|body(包含在logInByLdap结构中)|LDAP UID| |0.6| |password|String|body(包含在logInByLdap结构中)|密码| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "uuid": "2ce3cd4b2e5c441699edc09e612e916c", "accountUuid": "27df0ac39afd42eab643dfb1d448252b", "expiredDate": "Jun 7, 2017 9:20:34 PM" }, "accountInventory": { "uuid": "243382994e2643c18f5f5ec69305d866", "name": "test", "type": "Normal" } }

|名字|类型|描述|起始版本| |--|--|--|----| |success|boolean|成功标志|0.6| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventory|SessionInventory|详情参考inventory|0.6| |accountInventory|AccountInventory|详情参考accountInventory|0.6| |error|ErrorCode|详情参考error|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |accountUuid|String|账户UUID|0.6| |userUuid|String|用户UUID|0.6| |expiredDate|Timestamp|会话过期日期|0.6| |createDate|Timestamp|创建时间|0.6|

#accountInventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |name|String|资源名称|0.6| |description|String|资源的详细描述|0.6| |type|String|账户类型(管理员,普通账户)|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

SDK示例

Java SDK

LogInByLdapAction action = new LogInByLdapAction(); action.uid = "ou=Employee,uid=test"; action.password = "password"; LogInByLdapAction.Result res = action.call();

Python SDK

LogInByLdapAction action = LogInByLdapAction() action.uid = "ou=Employee,uid=test" action.password = "password" LogInByLdapAction.Result res = action.call()

Parent topic: AD/LDAP相关接口

获取AD/LDAP条目(GetLdapEntry)

API请求

URLs

GET zstack/v1/ldap/entry

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X GET http://localhost:8080/zstack/v1/ldap/entry?ldapFilter=(cn=user_xxx)&limit=2500.0

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |ldapFilter|String|query|查询条件| |2.2| |systemTags (可选)|List|query|系统标签| |2.2| |userTags (可选)|List|query|用户标签| |2.2| |limit (可选)|Integer|query|最多返回的记录数,类似MySQL的limit| |2.2|

API返回

返回示例

{ "inventories": [ { "attributes": [ { "id": "userPrincipalName", "orderMatters": false, "values": [ "weiqi@adtest.zs" ], "valuesAsNames": {} }, { "id": "displayName", "orderMatters": false, "values": [ "zstest" ], "valuesAsNames": {} }, { "id": "name", "orderMatters": false, "values": [ "weiqi" ], "valuesAsNames": {} }, { "id": "distinguishedName", "orderMatters": false, "values": [ "CN=weiqi,OU=ui,OU=zstest,DC=adtest,DC=zs" ], "valuesAsNames": {} }, { "id": "cn", "orderMatters": false, "values": [ "weiqi" ], "valuesAsNames": {} }, { "id": "objectClass", "orderMatters": false, "values": [ "top", "person", "organizationalPerson", "user" ], "valuesAsNames": {} } ], "dn": "CN=weiqi,OU=ui,OU=zstest,dc=adtest,dc=zs" } ], "success": true }

|名字|类型|描述|起始版本| |--|--|--|----| |inventories|List| |2.2| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|2.2|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|2.2| |description|String|错误的概要描述|2.2| |details|String|错误的详细信息|2.2| |elaboration|String|保留字段,默认为null|2.2| |opaque|LinkedHashMap|保留字段,默认为null|2.2| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|2.2|

SDK示例

Java SDK

GetLdapEntryAction action = new GetLdapEntryAction(); action.ldapFilter = "(cn=user_xxx)"; action.limit = 2500.0; action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"; GetLdapEntryAction.Result res = action.call();

Python SDK

GetLdapEntryAction action = GetLdapEntryAction() action.ldapFilter = "(cn=user_xxx)" action.limit = 2500.0 action.sessionId = "b86c9016b4f24953a9edefb53ca0678c" GetLdapEntryAction.Result res = action.call()

Parent topic: AD/LDAP相关接口

获取可绑定的AD/LDAP条目(GetCandidateLdapEntryForBinding)

获取可绑定的AD/LDAP条目(排除已绑定的AD/LDAP条目)。

API请求

URLs

GET zstack/v1/ldap/entries/candidates

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X GET http://localhost:8080/zstack/v1/ldap/entries/candidates?ldapFilter=(cn=user_xxx)&limit=2500.0

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |ldapFilter|String|query|查询条件| |2.2| |systemTags (可选)|List|query| | |2.2| |userTags (可选)|List|query| | |2.2| |limit (可选)|Integer|query|最多返回的记录数,类似MySQL的limit| |2.2|

API返回

返回示例

{ "inventories": [ { "attributes": [ { "id": "userPrincipalName", "orderMatters": false, "values": [ "weiqi@adtest.zs" ], "valuesAsNames": {} }, { "id": "displayName", "orderMatters": false, "values": [ "zstest" ], "valuesAsNames": {} }, { "id": "name", "orderMatters": false, "values": [ "weiqi" ], "valuesAsNames": {} }, { "id": "distinguishedName", "orderMatters": false, "values": [ "CN=weiqi,OU=ui,OU=zstest,DC=adtest,DC=zs" ], "valuesAsNames": {} }, { "id": "cn", "orderMatters": false, "values": [ "weiqi" ], "valuesAsNames": {} }, { "id": "objectClass", "orderMatters": false, "values": [ "top", "person", "organizationalPerson", "user" ], "valuesAsNames": {} } ], "dn": "CN=weiqi,OU=ui,OU=zstest,dc=adtest,dc=zs" } ], "success": true }

|名字|类型|描述|起始版本| |--|--|--|----| |inventories|List| |2.2| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|2.2|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|2.2| |description|String|错误的概要描述|2.2| |details|String|错误的详细信息|2.2| |elaboration|String|保留字段,默认为null|2.2| |opaque|LinkedHashMap|保留字段,默认为null|2.2| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|2.2|

SDK示例

Java SDK

GetCandidateLdapEntryForBindingAction action = new GetCandidateLdapEntryForBindingAction(); action.ldapFilter = "(cn=user_xxx)"; action.limit = 2500.0; action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"; GetCandidateLdapEntryForBindingAction.Result res = action.call();

Python SDK

GetCandidateLdapEntryForBindingAction action = GetCandidateLdapEntryForBindingAction() action.ldapFilter = "(cn=user_xxx)" action.limit = 2500.0 action.sessionId = "b86c9016b4f24953a9edefb53ca0678c" GetCandidateLdapEntryForBindingAction.Result res = action.call()

Parent topic: AD/LDAP相关接口

控制台相关接口

请求控制台访问地址(RequestConsoleAccess)

API请求

URLs

POST zstack/v1/consoles

Headers

Authorization: OAuth the-session-uuid

Body

{ "params": { "vmInstanceUuid": "b95acae48c804003ac3820751b58a50d" }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X POST -d '{"params":{"vmInstanceUuid":"e0442db541833083bd7e411a4d94d969"}}' \ http://localhost:8080/zstack/v1/consoles

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |vmInstanceUuid|String|body(包含在params结构中)|云主机UUID| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "scheme": "http", "hostname": "127.0.0.1", "port": 4900.0, "token": "d96caf24fae54c76b7652f548a258261" } }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventory|ConsoleInventory|详情参考inventory|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |scheme|String|访问协议类型|0.6| |hostname|String|宿主机名称|0.6| |port|int|端口|0.6| |token|String|口令|0.6|

SDK示例

Java SDK

RequestConsoleAccessAction action = new RequestConsoleAccessAction(); action.vmInstanceUuid = "c8925478e1f840caa1f3919affa19155"; action.sessionId = "f896abb919754292aa8d2f286596142c"; RequestConsoleAccessAction.Result res = action.call();

Python SDK

RequestConsoleAccessAction action = RequestConsoleAccessAction() action.vmInstanceUuid = "f37c825f87444941bf16261f63c7dbb7" action.sessionId = "331a21749df940e4b447e9103518890d" RequestConsoleAccessAction.Result res = action.call()

Parent topic: 控制台相关接口

查询控制台代理(QueryConsoleProxyAgent)

API请求

URLs

GET zstack/v1/consoles/agents GET zstack/v1/consoles/agents/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth 350b72c2d3f24641a767acbcec744b19" \ -X GET http://localhost:8080/zstack/v1/consoles/agents?q=uuid=745b7c17cd224025b3adfef4ae61b3d2

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth bb08e240616b482984c397e4517a021c" \ -X GET http://localhost:8080/zstack/v1/consoles/agents/8a3cc2be7e20420db29925e381c598bc

可查询字段

运行zstack-cli命令行工具,输入QueryConsoleProxyAgent并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

返回示例

{ "inventories": [ { "uuid": "c77bbc7d3364449e9543d0776a6087de", "managementIp": "127.0.0.1", "type": "ManagementServerConsoleProxy", "state": "Connected" } ] }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6| |inventories|List|详情参考inventories|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventories

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |description|String|资源的详细描述|0.6| |managementIp|String|管理节点IP|0.6| |type|String|类型|0.6| |status|String|状态(连接,断开)|0.6| |state|String|状态(启用,禁用)|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

QueryConsoleProxyAgentAction action = new QueryConsoleProxyAgentAction(); action.conditions = asList("uuid=dfbe49d87cb94d93b69354fa1270012b"); action.sessionId = "e2300cd4f74a457e87f13842aeb8fdef"; QueryConsoleProxyAgentAction.Result res = action.call();

Python SDK

QueryConsoleProxyAgentAction action = QueryConsoleProxyAgentAction() action.conditions = ["uuid=1e47046946f849ee871de20a2b045750"] action.sessionId = "1655d7f2e56d4710824cd1082bd5cc94" QueryConsoleProxyAgentAction.Result res = action.call()

Parent topic: 控制台相关接口

重连控制台代理(ReconnectConsoleProxyAgent)

API请求

URLs

PUT zstack/v1/consoles/agents

Headers

Authorization: OAuth the-session-uuid

Body

{ "params": { "agentUuids": [ "ce9f63639c6947fc9de43014a9c42af6", "5cf200f8fa6640278ab3751a9e40a122", "896f44bd3a2544e3b49a30dbe41303da" ] }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X PUT -d '{"reconnectConsoleProxyAgent":{"agentUuids":["9a00b78598253e68914541e6760ddeaa","c18fbd323fbd3902961e4105ec9364d0","96efd32908dd3f71bef8c0f414dbf828"]}}' \ http://localhost:8080/zstack/v1/consoles/agents

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |agentUuids (可选)|List|body(包含在params结构中)|控制台代理Agent的UUID| |0.6| |systemTags (可选)|List|body|系统标签| |0.6| |userTags (可选)|List|body|用户标签| |0.6|

API返回

返回示例

{ "inventory": { "976e8d54d42841da85eb697f3e8534b6": true, "ac4b5e3b69e5499eba381082199b5d42": true } }

|名字|类型|描述|起始版本| |--|--|--|----| |inventory|Map|控制台代理Agent清单|0.6| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|0.6|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

SDK示例

Java SDK

ReconnectConsoleProxyAgentAction action = new ReconnectConsoleProxyAgentAction(); action.agentUuids = asList("9b1d2cae4e75418ba8ca00a7f8d61eee","b3c9068b99664b65851bc29e39c3e336","89ea316d7f114203bb352d22b1f878e2"); action.sessionId = "607aa9478e0f452ab3fe43f0bb44771f"; ReconnectConsoleProxyAgentAction.Result res = action.call();

Python SDK

ReconnectConsoleProxyAgentAction action = ReconnectConsoleProxyAgentAction() action.agentUuids = [6b5d95576b444661a23454913abce886, 64326c502c4042b196d9602737733d64, 1cc5a9dbb4284fbe850e387788b365ec] action.sessionId = "dc7db7612de24cb7a3d91d1d08b03162" ReconnectConsoleProxyAgentAction.Result res = action.call()

Parent topic: 控制台相关接口

更新控制台代理(UpdateConsoleProxyAgent)

API请求

URLs

PUT zstack/v1/consoles/agents/{uuid}/actions

Headers

Authorization: OAuth the-session-uuid

Body

{ "updateConsoleProxyAgent": { "consoleProxyOverriddenIp": "127.0.0.1" }, "systemTags": [], "userTags": [] }

Note: 上述示例中systemTagsuserTags字段可以省略。列出是为了表示body中可以包含这两个字段。

Curl示例

curl -H "Content-Type: application/json" \ -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \ -X PUT -d '{"updateConsoleProxyAgent":{"consoleProxyOverriddenIp":"127.0.0.1"}}' \ http://localhost:8080/zstack/v1/consoles/agents/f616460f24cd330180db4188c3a905b6/actions

参数列表

|名字|类型|位置|描述|可选值|起始版本| |--|--|--|--|---|----| |uuid|String|url|资源的UUID,唯一标示该资源| |2.3| |consoleProxyOverriddenIp|String|body(包含在updateConsoleProxyAgent结构中)|新的控制台代理IP| |2.3| |systemTags (可选)|List|body|系统标签| |2.3| |userTags (可选)|List|body|用户标签| |2.3|

API返回

返回示例

{ "inventory": {} }

|名字|类型|描述|起始版本| |--|--|--|----| |error|ErrorCode|错误码,若不为null,则表示操作失败, 操作成功时该字段为null。 详情参考error|2.3| |inventory|ConsoleProxyAgentInventory|详情参考inventory|2.3|

#error

|名字|类型|描述|起始版本| |--|--|--|----| |code|String|错误码号,错误的全局唯一标识,例如SYS.1000, HOST.1001|0.6| |description|String|错误的概要描述|0.6| |details|String|错误的详细信息|0.6| |elaboration|String|保留字段,默认为null|0.6| |opaque|LinkedHashMap|保留字段,默认为null|0.6| |cause|ErrorCode|根错误,引发当前错误的源错误,若无原错误,该字段为null|0.6|

#inventory

|名字|类型|描述|起始版本| |--|--|--|----| |uuid|String|资源的UUID,唯一标示该资源|0.6| |description|String|资源的详细描述|0.6| |managementIp|String|管理节点IP|0.6| |type|String|类型|0.6| |status|String|状态(连接,断开)|0.6| |state|String|状态(启用,禁用)|0.6| |createDate|Timestamp|创建时间|0.6| |lastOpDate|Timestamp|最后一次修改时间|0.6|

SDK示例

Java SDK

UpdateConsoleProxyAgentAction action = new UpdateConsoleProxyAgentAction(); action.uuid = "f616460f24cd330180db4188c3a905b6"; action.consoleProxyOverriddenIp = "127.0.0.1"; action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"; UpdateConsoleProxyAgentAction.Result res = action.call();

Python SDK

UpdateConsoleProxyAgentAction action = UpdateConsoleProxyAgentAction() action.uuid = "f616460f24cd330180db4188c3a905b6" action.consoleProxyOverriddenIp = "127.0.0.1" action.sessionId = "b86c9016b4f24953a9edefb53ca0678c" UpdateConsoleProxyAgentAction.Result res = action.call()

Parent topic: 控制台相关接口

术语表

区域(Zone)

ZStack中最大的一个资源定义,包括集群、二层网络、主存储等资源。

集群(Cluster)

一个集群是类似物理主机(Host)组成的逻辑组。在同一个集群中的物理主机必须安装相同的操作系统(虚拟机管理程序,Hypervisor),拥有相同的二层网络连接,可以访问相同的主存储。在实际的数据中心,一个集群通常对应一个机架(Rack)。

管理节点(Management Node)

安装系统的物理主机,提供UI管理、云平台部署功能。

计算节点(Compute Node)

也称之为物理主机(或物理机),为云主机实例提供计算、网络、存储等资源的物理主机。

主存储(Primary Storage)

用于存储云主机磁盘文件的存储服务器。支持本地存储、NFS、 Ceph、FusionStor、Shared Mount Point等类型。

镜像服务器(Backup Storage)

也称之为备份存储服务器,主要用于保存镜像模板文件。建议单独部署镜像服务器。

镜像仓库(Image Store)

镜像服务器的一种类型,可以为正在运行的云主机快速创建镜像,高效管理云主机镜像的版本变迁以及发布,实现快速上传、下载镜像,镜像快照,以及导出镜像的操作。

云主机(VM Instance)

运行在物理机上的虚拟机实例,具有独立的IP地址,可以访问公共网络,运行应用服务。

镜像(Image)

云主机或云盘使用的镜像模板文件,镜像模板包括系统云盘镜像和数据云盘镜像。

云盘(Volume)

云主机的数据盘,给云主机提供额外的存储空间,共享云盘可挂载到一个或多个云主机共同使用。

计算规格(Instance Offering)

启动云主机涉及到的CPU数量、内存、网络设置等规格定义。

云盘规格(Disk Offering)

创建云盘容量大小的规格定义。

二层网络(L2 Network)

二层网络对应于一个二层广播域,进行二层相关的隔离。一般用物理网络的设备名称标识。

三层网络(L3 Network)

云主机使用的网络配置,包括IP地址范围、网关、DNS等。

公有网络(Public Network)

由因特网信息中心分配的公有IP地址或者可以连接到外部互联网的IP地址。

私有网络(Private Network)

云主机连接和使用的内部网络。

L2NoVlanNetwork

物理主机的网络连接不采用Vlan设置。

L2VlanNetwork

物理主机节点的网络连接采用Vlan设置,Vlan需要在交换机端提前进行设置。

VXLAN网络池(VXLAN Network Pool)

VXLAN网络中的 Underlay 网络,一个 VXLAN 网络池可以创建多个 VXLAN Overlay 网络(即 VXLAN 网络),这些 Overlay 网络运行在同一组 Underlay 网络设施上。

VXLAN网络(VXLAN)

使用 VXLAN 协议封装的二层网络,单个 VXLAN 网络需从属于一个大的 VXLAN 网络池,不同 VXLAN 网络间相互二层隔离。

云路由(vRouter)

云路由通过定制的Linux云主机来实现的多种网络服务。

安全组(Security Group)

针对云主机进行第三层网络的防火墙控制,对IP地址、网络包类型或网络包流向等可以设置不同的安全规则。

弹性IP(EIP)

公有网络接入到私有网络的IP地址。

快照(Snapshot)

某一个时间点上某一个磁盘的数据备份。包括自动快照和手动快照两种类型。

相关文档

咨询

021-61733682

400-962-2212