跳到主要内容

筛选条件

从快速开始的样例中的第二步中，我们使用了 /v2/api/get-vms 来获取虚拟机列表，这是一个查询用的 api，一个查询用的 API 的参数一般包括了以下几个部分：

筛选条件参数​

我们定义了 where 参数用于筛选资源，每一类资源都有自己的 WhereInput 类型，用于描述筛选条件，其中包含了一些常用的筛选条件，例如 VmWhereInput, ClusterWhereInput 等。

筛选某字段等于某个值​

例如筛选某字段等于对应值的资源，可以直接在 where 参数中传入对应的字段名和值，如果我们想筛选出 name 为 "demo" 的虚拟机，我们可以使用如下的 where 参数：

{
  "where": {
    "name": "demo"
  }
}

筛选某字段不等于某个值​

where 条件也可以筛选某字段不等于对应值的资源，可以直接在 where 参数中传入对应的字段名加上 _not 和对应的值，如果我们想筛选出 name 不为 "demo" 的虚拟机，可以使用如下的 where 参数：

{
  "where": {
    "name_not": "demo"
  }
}

筛选某字段是否属于某个集合​

where 条件支持为字段额外添加 _in 或者 _not_in 进行筛选，用于判断值是否处于或不处于某个集合，例如我们想筛选出 name 为 "demo" 或者 "demo2" 的虚拟机，可以使用如下的 where 参数：

{
  "where": {
    "name_in": ["demo", "demo2"]
  }
}

衍生的比较条件​

同时对于不同类型的字段，也会衍生出其他的比较用的筛选条件，以 int 举例，我们可以使用项的名称加上 _gt, _gte, _lt, _lte 来进行大于，大于等于，小于，小于等于的筛选，例如我们想筛选出 cpu 大于 2 的虚拟机，可以使用如下的 where 参数：

{
  "where": {
    "vcpu_gt": "2"
  }
}

不同的类型的字段有着自己的衍生，例如对于 string 类型的字段，我们可以使用项的名称加上 _contains, _starts_with, _ends_with, _not_contains, _not_starts_with, _not_ends_with ，具体的类型可以参考详细的 api 文档。

通过级联资源进行筛选​

单个级联资源​

如果资源的某项对应的的级联资源只有一个，那么级联资源筛选比较简单，类似于直接筛选某项等于某个值，不过筛选的条件从一个值变成了对应级联资源的 WhereInput 对象，例如一个虚拟机只可能属于一个集群，但是一个集群可能有多台虚拟机，如果我们想筛选出属于集群名为 clusterA 的虚拟机，可以使用如下的 where 参数：

{
  "where": {
    "cluster": {
      "name": "clusterA"
    }
  }
}
多个资源​

从上面的例子我们也可以直到一个集群可以有多个虚拟机，那么是否可以通过虚拟机来查询集群呢？答案是可以的，但是我们没法直接通过项来筛选。 我们可以使用对应项的名称加上 _every, _some, _none 来进行筛选，对应的条件仍然是对应集群的 WhereInput 对象， 三个不同的筛选条件分别表示了每个级联资源都满足，单个级联资源满足，或者每个级联资源都不满足对应的条件，这里我们引入 /v2/api/get-cluster api 来举例， 一个集群有多个虚拟机，如果希望筛选有任意一台虚拟机名为 demo 的集群，可以使用如下的 where 参数：

{
  "where": {
    "vms_some": {
      "name": "demo"
    }
  }
}

组合条件​

简单组合​

前面举得例子都只是用了一个条件，但是 where 条件本身并不受到条件数量的限制，同时不同的条件可以组合使用，例如我们想要筛选出属于集群名为 clusterA，cpu 大于 2 的虚拟机，我们可以使用如下的 where 参数：

{
  "where": {
    "cluster": {
      "name": "clusterA"
    },
    "vcpu_gt": "2"
  }
}
操作符组合​

对于一些比较复杂的条件，也可以使用 OR, NOT, AND 对 where 条件进行组合，这些筛选项的类型都是当前资源的 WhereInput 的数组，比如我们想筛选出属于集群名为 clusterA 或者属于，集群属于

{
  "where": {
    "OR": [
      {
        "cluster": {
          "name": "clusterA"
        }
      },
      {
        "cluster": {
          "name": "clusterB"
        }
      }
    ],
    "NOT": [{}]
  }
}