$filter 参数

有内置逻辑和数学运算符，可与结果集中的属性结合使用，以创建过滤器表达式。为了正确使用 $filter 表达式，必须遵循一些约定。属性是 API 响应中包含的字段。以下是一些准则：

要找出在某些 API 调用中对您可用的属性，请查看响应类模型。
字符串必须用单引号引起来，而属性、运算符和关键字则不需要：
```
$filter=Name eq 'Altoro'
```
有时，您要在表达式中使用的属性嵌在另一个属性中。例如，在 Get /api/v4/Scans 调用中返回的扫描 JSON 对象在其 LatestExecution 属性中嵌入了 JSON 对象。要引用此嵌套字段，请使用斜杠。例如，要仅返回最新扫描执行状态为就绪的扫描，请使用斜杠：
```
$filter=LatestExecution/Status eq 'Ready'
```
这也可以在其他 OData 参数中使用，例如：
```
$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 规范。

表 1. 运算符
组	操作员	含义
关系	`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 规范。

表 2. 字符串运算符
字符串函数	示例	含义
`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'`	连接两个字符串。

日期特定函数

这些函数通常返回日期的特定部分，例如日期对象中的某月某日。

表 3. 日期函数
日期函数	示例
`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`

数学函数

表 4. 数学函数
数学函数	含义
`round`	四舍五入到最接近的整数
`floor`	下舍入到最接近的整数
`ceiling`	上舍入到最接近的整数