概览

对于运营大规模云的企业用户来说,最大的挑战之一是快速精准定位所需资源。例如,需要从100,000台虚拟机中找到拥有EIP(17.12.53.8)的虚拟机。ZStack Cloud提供了丰富全面的API可以用来查询所有资源的每一个域,具体参看《开发手册》的查询API章节了解设计架构。


架构(Architecture)

每个ZStack Cloud资源都依据属性(properties)组织成JSON格式的清单(inventory)。

例如,区域(Zone)清单:
{             "createDate": "Nov 17, 2017 8:27:47 PM",             "description": "Test",             "lastOpDate": "Nov 20, 2017 5:40:52 PM",             "name": "Zone-1",             "state": "Enabled",             "type": "zstack",             "uuid": "c3a228078e8c4f81ba7da0b16fb8d77f"         }
一个资源清单可以包含其他资源的清单;例如,一个L3网络清单包含IP范围(IP Range)清单:
{             "category": "Public",             "createDate": "Nov 17, 2017 9:11:59 PM",             "dns": [                 "223.5.5.5"             ],             "ipRanges": [                 {                     "createDate": "Nov 17, 2017 9:18:47 PM",                     "endIp": "10.108.10.110",                     "gateway": "10.0.0.1",                     "l3NetworkUuid": "a8b7054aaa9141f696afebdb1721e5c8",                     "lastOpDate": "Nov 17, 2017 9:18:47 PM",                     "name": "L3-Pub",                     "netmask": "255.0.0.0",                     "networkCidr": "10.0.0.1/8",                     "startIp": "10.108.10.100",                     "uuid": "df5b1ab49a53440bb44eb14c7ebfd50a"                 }             ],             "l2NetworkUuid": "16fecf5ff5754c3fb6669986ec1fe645",             "lastOpDate": "Nov 17, 2017 9:11:59 PM",             "name": "L3-Pub",             "networkServices": [                 {                     "l3NetworkUuid": "a8b7054aaa9141f696afebdb1721e5c8",                     "networkServiceProviderUuid": "3d46e334773845adac0d90c86a5999ee",                     "networkServiceType": "Userdata"                 },                 {                     "l3NetworkUuid": "a8b7054aaa9141f696afebdb1721e5c8",                     "networkServiceProviderUuid": "3d46e334773845adac0d90c86a5999ee",                     "networkServiceType": "Eip"                 },                 {                     "l3NetworkUuid": "a8b7054aaa9141f696afebdb1721e5c8",                     "networkServiceProviderUuid": "3d46e334773845adac0d90c86a5999ee",                     "networkServiceType": "DHCP"                 }             ],             "state": "Enabled",             "system": false,             "type": "L3BasicNetwork",             "uuid": "a8b7054aaa9141f696afebdb1721e5c8",             "zoneUuid": "c3a228078e8c4f81ba7da0b16fb8d77f"         }
清单中的域(field)分为两类:原生域(primitive field)和嵌套域(nested field)
  • 原生域是由一个基本类型(primitive type)构成的域,如数字(number)、字符串(string)、布尔(boolean)、或日期(date);在上述示例中,uuidnamesystem都是原生域。
  • 嵌套域通常是由代表其它资源数据类型组合而成; 在上述示例中,ipRanges就是一个嵌套域。
说明:
  • 除非特别声明,所有清单的所有域都是可以被查询的。
  • 对于一个清单,通常都有对应的查询API;例如,QueryZone、QueryHost、QueryVmInstance等。
  • 查询API通常返回一个清单列表,在没有匹配结果时会返回一个空列表。
  • 一个查询的结果类似于:
    {     "inventories": [         {             "allocatorStrategy": "LeastVmPreferredHostAllocatorStrategy",             "cpuNum": 1,             "cpuSpeed": 0,             "createDate": "Nov 17, 2017 8:48:06 PM",             "lastOpDate": "Nov 17, 2017 8:48:06 PM",             "memorySize": 1073741824,             "name": "instance-offering",             "sortKey": 0,             "state": "Enabled",             "type": "UserVm",             "uuid": "32c3405f7bbf43009cfaf58cb41e39fc"         }     ],     "success": true }

查询API由一个查询条件(query conditions)的列表和一些辅助参数(helper parameters)构成:

查询API的参数(Parameters)

名字 描述 此参数可选 可选参数值 起始支持版本
conditions :ref:`QueryCondition <QueryCondition>`组成的列表 0.6
limit 允许查询API返回清单的最大数量;默认为1000 true 0.6
start 返回清单的起始编号;默认为0 true 0.6
count 如果为true, 查询响应只返回清单数量;默认为false
  • true
  • false
0.6
replyWithCount 如果为true, 查询响应会同时返回清单及其数量;默认为false
  • true
  • false
0.6
sortBy 指定的域被作为排序依据;这个域必须是原生域 true 0.6
sortDirection 如果sortBy不等于null,这个域指定排序方向;默认为asc
  • asc
  • desc
0.6
fields 原生域组成的一个列表;指定时, 查询返回的清单只会包含这些域 true 0.6

查询条件(Query Condition)

查询API接受查询条件组成的列表,查询条件包含以下属性:
名字 描述 此参数可选 可选的参数值 起始支持版本
name 域名 0.6
op 比较操作符(comparison operator)
  • =
  • !=
  • >
  • >=
  • <
  • <=
  • in
  • not in
  • is null
  • is not null
  • like
  • not like
0.6
value 查询值 0.6
域名可以是原生域的名字,也可以是嵌套域的子域名字,或者是扩展域(expanded field)的子域(sub-field)名字(请参看:ref:Join <query join>); op是SQL语言中的比较操作符。
操作符 CLI格式 描述
= = 等于操作符; 字符串比较区分大小写
!= != 不等于操作符; 字符串比较区分大小写
> > 大于操作符; 字符串比较请参看MySQL的规范
>= >= 大于等于操作符; 字符串比较请参看MySQL的规范
< < 小于; 字符串比较请参看MySQL的规范
<= <= 小于或等于操作符; 字符串比较请参看MySQL的规范
in ?= 检查一个值是否在一个集合内
not in !?= 检查值是否不在一个集合内
is null =null NULL值测试
is not null !=null 非NULL值测试
like ~= 简单模式匹配;用%匹配任一数量的字符, 甚至零个字符; 用_匹配单个字符
not like !~= 简单模式匹配的反式;用%匹配任一数量的字符, 甚至零个字符;用_匹配单个字符
查询条件之间的关系是逻辑与(logical AND), 当前版本只支持这种关系,例如:
#用来查找名字为L3Network1的L3网络,并且这个网络有一个或多个IP范围的名字是range1 QueryL3Network ipRanges.name=range1 name=L3Network1

CLI查询条件

有两种方式可以在CLI中使用查询条件:
  • 一种是查询API的原始形式:
    QueryHost conditions='[{"name":"name", "op":"=", "value":"KVM1"}]'
  • 另一种是CLI格式:
    QueryHost name=KVM1
显然,CLI格式更直观更容易理解。CLI格式通常使用以下格式表示查询条件:
condition_name(no_space)CLI_comparison_operator(no_space)condition_value
在CLI中键入命令时, 你可以使用*Tab*来自动补全或者提示包括原生域,嵌套域以及扩展域在内的可以被查询的域:
admin >>>QueryVmInstance [Query Conditions:] allVolumes.            cluster.               host.                  image.                 instanceOffering. resourcePool.          rootVolume.            vmCdRoms.              vmNics.                zone.   __systemTag__=         __tagUuid__=           __userTag__=           allocatorStrategy=     clusterUuid= cpuNum=                cpuSpeed=              createDate=            defaultL3NetworkUuid=  description= groupBy=               hostUuid=              hypervisorType=        imageUuid=             instanceOfferingUuid= lastHostUuid=          lastOpDate=            memorySize=            name=                  platform= rootVolumeUuid=        state=                 systemTags=            type=                  userTags= uuid=                  zoneUuid=  [Parameters:] count=                 fields=                limit=                 replyWithCount=        sortBy= sortDirection=         start=                 timeout=

联结(Join)扩展查询(expanded query)

ZStack Cloud中联结(Join)被称为扩展查询(expanded query);这种查询允许通过其它和要查询的目标资源有关系的资源的域来查询;在ZStack Cloud的术语中这些域被称为扩展域。

例如,依据云主机的网卡(nic)拥有EIP的VIP为10.108.10.102来查询其L3网络:
admin >>>QueryL3Network vmNic.eip.vipIp=10.108.10.102

上述示例中,L3网络的清单没有vmNic.eip.vipIp域;但此IP地址与云主机的网卡nic清单有关系,而云主机的网卡nic清单又与EIP清单有关系;可以构造一个跨越三个清单的扩展查询:L3网络清单、云主机nic清单、和EIP清单。

基于此联结扩展查询条件,ZStack Cloud可以提供将近400万种查询条件以及无穷无尽的组合条件。

以下是构造的复杂示例,用于展示强大的查询功能:
QueryVolumeSnapshot volume.vmInstance.vmNics.l3Network.l2Network.attachedClusterUuids?=13238c8e0591444e9160df4d3636be82

此查询用于查找云盘快照,此查询依赖云盘所在的云主机,云主机所在的L3网络的L2网络被挂载在一个uuid为13238c8e0591444e9160df4d3636be82的集群上。

查询列表(Query List)

当一个域是列表的时候,可以包含类似int、long、string的基本类型或者嵌套清单。

查询列表并不特殊;编写本章节只是用来提醒大家,不要误认为只能用in(?=)和not in(!?=)来查询一个列表域;实际上,我们可以使用所有的比较操作符。

例如:
#查找所有的拥有类似72.72.72.*的DNS的L3网络 QueryL3Network dns~=72.72.72.%
#查找所有的IP范围从192.168.0.10开始的L3网络 QueryL3Network ipRanges.startIp=192.168.0.10

查询标签(Query Tags)

在这一节中:ref:`tags <tag>`你会看到所有的资源都可以用系统标签(system tags)和用户标签(user tags),它们都可以作为查询条件。

ZStack Cloud使用两个特别的域: __userTag____systemTag__来做查询。

例如:
QueryVmInstance __userTag__?=web-tier-VMs
QueryHost __systemTag__?=os::distribution::Ubuntu managementIp=192.168.0.212
  • 操作符>>=<<=只会返回拥有满足条件的标签的资源;
  • is not null会返回所有拥有标签的资源;
  • is null会返回所有没有标签的资源;
  • !=not innot like会返回拥有的标签不满足条件的以及没有标签的所有资源。

避免循环查询(Avoid Loop Query)

大多数ZStack Cloud资源拥有双向的扩展查询。

例如,主机拥有扩展至集群的扩展查询,而集群也拥有扩展至主机的扩展查询。这使得从任意方向查询资源成为可能,但同时也可能导致查询循环。

例如:
QueryHost vmInstance.vmNics.eip.vmNic.vmInstance.uuid=d40e459b97db5a63dedaffcd05cfe3c2
就是一个循环查询, 它和下面的查询作用相同:
QueryHost vmInstance.uuid=d40e459b97db5a63dedaffcd05cfe3c2

循环查询的行为是未定义的;有可能得到也有可能得不到正确的结果。因此,请避免使用循环查询。

有效的使用查询

查询API很强大,可以通过不同的查询方式得到相同的结果。

例如, 要查找运行在UUID为e497e90ab1e64db099eea93f998d525b的物理机上的云主机:

方式一:
QueryVmInstance hostUuid=e497e90ab1e64db099eea93f998d525b
方式二:
QueryVmInstance host.uuid=e497e90ab1e64db099eea93f998d525b

上述示例中,方式一更高效,因为它只是用了VM表的原生域进行查询;方式二使用了联结VM表和host表的扩展查询。

当查询条件是UUID的时候,建议使用原生域而非扩展域的子域进行查询。


示例

普通查询

QueryVmInstance defaultL3NetworkUuid=7e52c8b7b6f94e4485a61f3f1a8bfe42 QueryPortForwardingRule protocolType=TCP

查询计数

QueryVmInstance defaultL3NetworkUuid=7e52c8b7b6f94e4485a61f3f1a8bfe42 count=true QueryPortForwardingRule protocolType=TCP count=true

带计数的普通查询

QueryVmInstance defaultL3NetworkUuid=7e52c8b7b6f94e4485a61f3f1a8bfe42 replyWithCount=true QueryPortForwardingRule protocolType=TCP replyWithCount=true

设置限制

QueryVmInstance defaultL3NetworkUuid=7e52c8b7b6f94e4485a61f3f1a8bfe42 limit=3 QueryPortForwardingRule protocolType=TCP limit=2

设置条件

QueryVmInstance name~=clone QueryPortForwardingRule vipPortStart?=23,24

设置起始

QueryVmInstance imageUuid=4b5e37a47a402977a3b285ccecf9c0c1 start=2 limit=3 QueryPortForwardingRule protocolType=TCP start=1 limit=3

选择域

QueryVmInstance fields=name,uuid clusterUuid=5cac8330d5ab4c2ea393b8c3986c8850 QueryPortForwardingRule fields=uuid,privatePortStart,privatePortEnd vipPortStart=23 vipPortEnd=23

排序

QueryVmInstance clusterUuid=5cac8330d5ab4c2ea393b8c3986c8850 sortBy=createDate sortDirection=asc QueryPortForwardingRule sortBy=privatePortStart sortDirection=desc

历史文档

学习路径

ZStack Cloud 产品学习路径

版本号:

5.3.0
4.8.10
常见问题
常见问题

ZStack Cloud 产品学习路径

快速梳理文档,点击相应文本链接,快速跳转到相应文档的页面,学习 ZStack Cloud 产品。

我知道了

升级提醒

若您选择升级至4.0.0及之后版本,请注意以下功能调整:

1. 云路由器全面升级为VPC路由器,云路由网络全面升级为VPC网络,不再单独设云路由器页面。升级全程无感知,相关业务不受任何影响。

2. 企业管理账号体系取代用户组与用户,不再单独设用户/用户组页面,不可再使用用户/用户组账号登录云平台。升级前,请先将“用户组与用户”纳管的账号数据妥善迁移至“企业管理”纳管,再执行升级操作。注意:对于admin创建并具备admin权限的用户账号同步取消,如有需要,可使用企业管理账号体系中的平台管理员实现相同功能。

3. 调整AD/LDAP与账户的对接管理方式,统一由企业管理纳管,不再单独设AD/LDAP页面。升级前,请先将“账户”对接纳管的AD/LDAP账号数据妥善迁移至“企业管理”纳管,再执行升级操作。

如对上述升级提醒有任何疑问或需要升级帮助,请联系ZStack官方技术支持

下载ZStack企业版

您已填写过基本信息?点击这里

姓名应该不少于两个字符
手机号格式错误
验证码填写错误 获取短信验证码 60 秒后可重发
公司名称不应该少于4个字符
邮箱格式错误

下载链接将会通过邮件形式发送至您的邮箱,请谨慎填写。

同意 不同意

我已阅读并同意云轴科技 《法律声明》《隐私政策》用户管理规则及公约

下载ZStack企业版

还未填写过基本信息?点击这里

邮箱或手机号码格式错误
同意 不同意

我已阅读并同意云轴科技 《法律声明》《隐私政策》用户管理规则及公约

验证手机号
手机号格式错误
验证码填写错误 获取短信验证码 60 秒后可重发
同意 不同意

我已阅读并同意云轴科技 《法律声明》《隐私政策》用户管理规则及公约

登录观看培训视频
仅对注册用户开放,请 登录 观看培训视频

业务咨询:

400-962-2212 转 1

售后咨询:

400-962-2212 转 2

其他(漏洞提交、投诉举报等)

400-962-2212 转 3
ZStack认证培训咨询
姓名应该不少于两个字符
手机号格式错误
验证码填写错误 获取短信验证码 60 秒后可重发
公司名称不应该少于4个字符
邮箱格式错误

同意 不同意

我已阅读并同意云轴科技 《法律声明》《隐私政策》用户管理规则及公约

业务咨询:

400-962-2212 转 1

ZStack学院:

training@zstack.io
申请ZStack多机版
姓名应该不少于两个字符
手机号格式错误
验证码填写错误 获取短信验证码 60 秒后可重发
公司名称不应该少于4个字符
邮箱格式错误

同意 不同意

我已阅读并同意云轴科技 《法律声明》《隐私政策》用户管理规则及公约

业务咨询:

400-962-2212 转 1

售后咨询:

400-962-2212 转 2

其他(漏洞提交、投诉举报等)

400-962-2212 转 3
立即咨询
姓名应该不少于两个字符
手机号格式错误
验证码填写错误 获取短信验证码 60 秒后可重发
公司名称不应该少于4个字符
邮箱格式错误

同意 不同意

我已阅读并同意云轴科技 《法律声明》《隐私政策》用户管理规则及公约

业务咨询:

400-962-2212 转 1

售后咨询:

400-962-2212 转 2

其他(漏洞提交、投诉举报等)

400-962-2212 转 3
培训认证合作伙伴申请
姓名应该不少于2个字符
手机号格式错误
验证码填写错误 获取短信验证码 60 秒后可重发
邮箱格式错误
城市名称不应该少于2个字符
公司名称不应该少于4个字符
职位名称不应该少于2个字符

同意 不同意

我已阅读并同意云轴科技 《法律声明》《隐私政策》用户管理规则及公约

业务咨询:

400-962-2212 转 1

商务联系:

channel@zstack.io
ZStack&工信人才联合证书申请
已获得ZStack原厂证书
未获得ZStack原厂证书
请填写您的基本信息
姓名应该不少于2个字符
手机号格式错误
验证码填写错误 获取短信验证码 60 秒后可重发
邮箱格式错误
城市名称不应该少于2个字符
公司/学校名称不应该少于4个字符
证书类型
ZCCT
ZCCE
ZCCA
ZCPC-ISP
申请ZStack&工信人才联合证书须支付工本费,是否可以接受
同意 不同意

我已阅读并同意云轴科技 《法律声明》《隐私政策》用户管理规则及公约

业务咨询:

400-962-2212 转 1

商务联系:

channel@zstack.io

下载链接已发送至您的邮箱。

如未收到,请查看您的垃圾邮件、订阅邮件、广告邮件。 当您收到电子邮件后,请点击 URL 链接,以完成下载。

下载链接已发送至您的邮箱。

如未收到,请查看您的垃圾邮件、订阅邮件、广告邮件。
或点击下方URL链接 (IE内核浏览器请右键另存为), 完成下载:

感谢您使用 ZStack 产品和服务。

成功提交申请。

我们将安排工作人员尽快与您取得联系。

感谢您使用 ZStack 产品和服务。

信息提交成功。

我们将安排工作人员尽快与您取得联系,请保持电话畅通。

感谢您使用 ZStack 产品和服务。

预约沟通

联系我们

业务咨询
400-962-2212 转 1
售后咨询
400-962-2212 转 2
其他业务(漏洞提交、投诉举报等)
400-962-2212 转 3

联系我们

回到顶部

产品试用申请
请选择您要试用的产品
ZStack Cloud 企业版
ZStack Cloud 混合云版
ZStack Cloud 基础版
ZStack Cloud 标准版
请填写您的基本信息
姓名应该不少于两个字符
手机号格式错误
验证码填写错误 获取短信验证码 60 秒后可重发
公司名称不应该少于4个字符
邮箱格式错误

商务咨询:

400-962-2212 转 1

售后咨询:

400-962-2212 转 2

商务联系:

sales@zstack.io

成功提交申请。

我们将安排工作人员尽快与您取得联系。

感谢您使用 ZStack 产品和服务。