$filter 参数
$filter
是最强大的 OData 参数。它有许多运算符。
有内置逻辑和数学运算符,可与结果集中的属性结合使用,以创建过滤器表达式。为了正确使用
$filter
表达式,必须遵循一些约定。属性是 API 响应中包含的字段。以下是一些准则:- 要找出在某些 API 调用中对您可用的属性,请查看响应类模型。
- 字符串必须用单引号引起来,而属性、运算符和关键字则不需要:
$filter=Name eq 'Altoro'
- 有时,您要在表达式中使用的属性嵌在另一个属性中。例如,在
Get /api/v4/Scans
调用中返回的扫描 JSON 对象在其LatestExecution
属性中嵌入了 JSON 对象。要引用此嵌套字段,请使用斜杠。例如,要仅返回最新扫描执行状态为就绪的扫描,请使用斜杠:
这也可以在其他 OData 参数中使用,例如:$filter=LatestExecution/Status eq 'Ready'
$orderby=LatestExecution/ScanEndTime desc
- 如果使用日期进行比较,则日期必须采用 EDM 格式(例如
2018-06-26T09:13:28z
)。因此,为了在特定日期之后创建扫描,可以将CreatedAt
字段与特定日期进行比较,将 EDM 日期字符串转换为 DateTime 对象:$filter=CreatedAt gt 2018-07-31T07:30:00z
运算符
上述示例使用运算符,例如
eq
表示“等于”,而 gt
是“大于”。以下是一些常见的逻辑/数学运算符。有关 OData 运算符的更完整列表,请参见参考资料中的 OData v3 规范。组 | 操作员 | 含义 |
---|---|---|
关系 | gt |
大于 |
ge |
大于或等于 | |
lt |
少于 | |
le |
小于或等于 | |
isof |
类型判断 | |
相等 | eq |
等于 |
ne |
不等于 | |
条件 AND | and |
逻辑 And |
条件 OR | or |
逻辑 Or |
Lambda 运算符
Lambda 运算符支持更高级的表达式过滤。有两个 Lambda 运算符,即any
和 all
。它们用于包含需要操作的值数组的字段。如果表达式中至少有一个结果的计算结果为 true,则 any
的计算结果为 true。所有结果对运算符 all
的求值结果都必须为 true 才能返回 true。例如,考虑
/api/v4/Apps
API:每个应用程序都以 ComplianceStatuses 数组的形式返回,与应用程序相关联的每个策略返回一个。- 返回不含失败策略的所有应用程序:
$filter=ComplianceStatuses/all(d:d/Compliant eq true)
- 返回包含至少一个失败策略的所有应用程序:
$filter=ComplianceStatuses/any(d:d/Compliant eq false)
字符串运算符
字符串运算符很有用,因为大多数用例并不包含完全相等的字符串。通常,您需要字符串函数,例如substring
或 endswith
。这些函数包含在 OData 中。以下列表摘自 OData 规范。字符串函数 | 示例 | 含义 |
contains |
contains(Name,'Altoro') |
如果字符串包含子字符串,则返回 true。 |
endswith |
endswith(Name,'Mutual') |
如果字符串以子字符串结尾,则返回 true。 |
startswith |
startswith(Name,'Altoro') |
如果字符串以子字符串开头,则返回 true。 |
length |
length(Name) gt 10 |
返回字符串(或数组)的长度 |
indexof |
indexof(Name,'Altoro') eq 1 |
返回子字符串开头的索引 |
substring |
substring(Name,1) eq 'toro Mutual' |
返回从索引开始的字符串。 |
tolower |
tolower(Name) eq 'altoro mutual' |
将字符串转换为小写。 |
toupper |
toupper(Name) eq 'ALTORO MUTUAL' |
将字符串转换为大写。 |
trim |
trim(Name) eq 'Altoro Mutual' |
截去尾部和前导空格。 |
concat |
concat(Name,' Financial') eq 'Altoro Mutual Financial' |
连接两个字符串。 |
日期特定函数
这些函数通常返回日期的特定部分,例如日期对象中的某月某日。日期函数 | 示例 |
year |
year(ScanEndTime) eq 2024 |
month |
month(ScanEndTime) eq 12 |
day |
day(ScanEndTime) eq 8 |
hour |
hour(ScanEndTime) eq 1 |
minute |
minute(ScanEndTime) eq 0 |
second |
second(ScanEndTime) eq 0 |
数学函数
数学函数 | 含义 |
round |
四舍五入到最接近的整数 |
floor |
下舍入到最接近的整数 |
ceiling |
上舍入到最接近的整数 |