筛选集合
使用 filter 查询字符串参数,客户端可以筛选请求返回的 Item 集合。 对于集合中的每个资源,都会使用通过 filter 指定的表达式进行求值。响应中只包含表达式求值为 true 的项。 响应中不包含表达式求值为 false 或 null 的项,或引用不可用属性的项。
OneDrive API 仅支持官方 OData 4.0 筛选器语法的以下子集。
注意: 为了提高可读性,示例省略了正确的 URL 编码。 实际使用的筛选器语法必须经过 URL 编码。
示例:返回价格低于 10.00 美元的所有产品
GET /Products?filter=Price lt 10.00
filter 选项值是布尔表达式。
支持的运算符
OneDrive API 在 filter 语法中支持以下运算集。
| 运算符 | 说明 | 示例 |
|---|---|---|
eq |
等于 | city eq 'Redmond' |
ne |
不等于 | city ne 'London' |
gt |
大于 | price gt 20 |
ge |
大于或等于 | price ge 10 |
lt |
小于 | price lt 20 |
le |
小于或等于 | price le 10 |
and |
逻辑与 | price le 200 and price gt 3.5 |
or |
逻辑或 | price le 3.5 or price gt 200 |
( ) |
优先级分组 | (priority eq 1 or city eq 'Redmond') and price gt 100 |
运算符优先级
filter 语法的运算符按以下顺序(优先级从高到低)进行求值。 同一组/类别的运算符的优先级相同,按从左到右的顺序进行求值。
| 组 | 运算符 | 说明 |
|---|---|---|
| 分组 | ( ) |
优先级分组 |
| 关系 | gt |
大于 |
ge |
大于或等于 | |
lt |
小于 | |
le |
小于或等于 | |
| 相等 | eq |
等于 |
ne |
不等于 | |
| 条件与 | and |
逻辑与 |
| 条件或 | or |
逻辑或 |
可筛选属性
虽然 filter 语法可用于筛选项的任意属性,但我们还是优化了以下特定属性,以便可以快速高效地筛选它们。
注意: 在 OneDrive for Business、SharePoint Online 和 SharePoint Server 2016 中,仅支持筛选 name 和 url 属性。
- audio
- createdDateTime (for gt, ge, lt, le)
- deleted
- file
- folder
- image
- lastModifiedDateTime (for gt, ge, lt, le)
- video
筛选未经优化的其他属性可能会引发以下行为:
- API 延迟较高(响应返回时间较长)
- 空网页(值集合中没有任何项,只有下一页的 odata.nextLink 属性)
示例
下面的示例在搜索结果中筛选出只包含 File 和 Image Facet 的项。
请求
GET /drive/root/search(q='vacation')?filter=image%20ne%20null%20and%20file%20ne%20null
响应
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [
{
"id": "0123456789abc!123",
"name": "Vacation.jpg",
"image": { },
"file": { },
"searchResult":
{
"onClickTelemetryUrl": "https://bing.com/0123456789abc!123"
}
},
{
"id": "0123456789abc!456",
"name": "Summer.jpg",
"image": { },
"file": { },
"searchResult":
{
"onClickTelemetryUrl": "https://bing.com/0123456789abc!456"
}
}
],
"@search.approximateCount": 12,
"@odata.nextLink": "https://api.onedrive.com/drive/root/search?query=vacation&skipToken=1asdlnjnkj1nalkm!asd"
}