筛选集合

使用 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 中,仅支持筛选 nameurl 属性。

  • audio
  • createdDateTime (for gt, ge, lt, le)
  • deleted
  • file
  • folder
  • image
  • lastModifiedDateTime (for gt, ge, lt, le)
  • video

筛选未经优化的其他属性可能会引发以下行为:

  • API 延迟较高(响应返回时间较长)
  • 空网页(值集合中没有任何项,只有下一页的 odata.nextLink 属性)

示例

下面的示例在搜索结果中筛选出只包含 FileImage 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"
}