该Control Room API 支持对返回资源数组的端点进行筛选、分页和排序。

筛选机制筛选所需的资源；排序机制按顺序排列资源；分页机制则返回特定范围的这些有序资源。 本主题为您提供有关筛选和排序 API 请求结果的详细信息，并指导您对 API 请求返回的大量结果集进行分页。
注：
  • 支持对子字符串进行排序和筛选。 例如，如果要搜索其名称中包含 fin 的 机器人 或文件，请输入 fin 作为搜索条件。 将显示所有名称中包含 fin 的 机器人 和文件，例如，Finance、Finder、DeltaFinance 和 Dolfin。
  • 不支持使用通配符搜索和筛选 机器人 或文件。

筛选

筛选功能允许您对返回的资源集应用布尔条件，以便对资源集进行子集筛选，仅保留条件为真的资源。 Control Room API 筛选器中的最基本运算符是将字段与给定值进行比较。 可以使用相等性比较、范围比较或逻辑。 使用以下运算符将字段与常量值进行比较。
工作 描述 示例
相等性比较
等于 等于 用户电子邮箱地址，等于 first.last@aa.com
ne 不等于 用户电子邮箱地址，不等于 first.last@aa.com
范围比较
lt 小于 数量小于1500
le 小于或等于 数量小于或等于1500
ge 大于或等于 CreatedDateUtc 大于或等于 2021 年 3 月 15 日
gt 大于 CreatedDateUtc 大于或 2021 年 3 月 15 日
逻辑
和 企业用户现在 Field1 eq 'abc' and Field2 eq 'def'
或 或 Field1 eq 'abc' or Field2 eq 'def'
通过筛选器查询参数，您可以对请求应用基本、多重以及基于约定的筛选器。 Control Room API 中的筛选器可以使用单个参数或多个参数。

单参数筛选器

单参数筛选器允许 API 请求通过将响应中的一个或多个成员与查询中传递的值进行匹配来选择响应。 下图呈现的是单参数筛选器：
单参数筛选器

与上图（单参数过滤器）对应的 JSON 格式如下：
{ "filter": { "operator": "<NONE, lt, le, eq, ne, ge, gt, substring, and, or, not>", "field": "string", "value": "string" } }

例如，要列出所有包含子字符串 finance 的设备池，请使用以下单参数筛选器：

POST http://{{ControlRoomURL}}/v2/devices/pools/list
{ "filter":{ "operator":"substring", "field":"name", "value":"finance" } }

有关单参数过滤器的更详细示例，请参阅 设备池 API 。

多参数筛选器

多参数筛选器允许您根据逻辑操作数 and 和 or 中包裹的多个条件筛选结果。
  • and： 一个二元运算符，如果操作数中的所有条件评估为真，则评估为真。
    多参数筛选器 - AND
  • or： 一个二元运算符，如果操作数中至少有一个条件评估为真，则评估为真。
    多参数筛选器 - OR
与上图（多参数筛选器）对应的 JSON 格式如下：
{ "filter": { "operator": "<and, or>", "operands": [ { "operator": "<NONE, lt, le, eq, ne, ge, gt, substring, and, or, not>", "field": "string", "value": "string" }, { "operator": "<NONE, lt, le, eq, ne, ge, gt, substring, and, or, not>", "field": "string", "value": "string" } ] } }

例如，要列出所有包含子字符串设备的角色，createdOn 在 2022 年 4 月 1 日之后，且 createdOn 在2022 年 5 月 31 日 之前，请使用逻辑添加运算符进行多参数筛选，如下所示：

POST http://{{ControlRoomURL}}//v1/usermanagement/roles/list
{ "filter":{ "operator":"and", "operands":[ { "operator":"substring", "field":"name", "value":"Device" }, { "operator":"gt", "field":"createdOn", "value":"2022-04-01T00:00:00.989Z" }, { "operator":"lt", "field":"createdOn", "value":"2022-05-31T23:00:00.123Z" } ] } }

有关单参数过滤器的更详细示例，请参阅 用户管理 API 。

分页

分页功能允许您：
  • 检索有限的结果集。
  • 偏移结果集。
所有返回记录集的 Control Room API 都进行了分页处理。 支持分页的 API 方法需要两个（可选）参数：
工作 描述
offset 偏移参数控制响应结果集中的起始点。 默认值为 0。
长度 长度参数是从偏移开始检索的最大记录数。 默认值为 200。
分页的 JSON 代码段如下所示：
"page":{ "offset":5, "length":10 }

有关单参数过滤器的更详细示例，请参阅 用户管理 API 。

排序

通过排序功能，您可以按任何字段对结果进行升序或降序排序。 例如，如果要返回角色，可以按最后修改日期排序。

"sort": [ { "field": "string", "direction": "<asc, desc>" }

方向

类型： Enum [ desc, asc ]

  • acc = 升序（最小到最大，0 到 9，A 到 Z）
  • desc = 降序（最大到最小，9 到 0，Z 到 A）

有关单参数过滤器的更详细示例，请参阅 用户管理 API 。