在 SharePoint REST 请求中使用 OData 查询操作Use OData query operations in SharePoint REST requests

准备工作Before you start

SharePoint REST 服务支持多种 OData 查询字符串运算符,使用这些运算符,您可以选择、筛选及订购您请求的数据。The SharePoint REST service supports a wide range of OData query string operators that enable you to select, filter, and order the data you request.

提示

SharePoint Online(和本地 SharePoint 2016 及更高版本)REST 服务支持使用 OData $batch 查询选项,将多个请求合并到一个服务调用中。The SharePoint Online (and on-premises SharePoint 2016 and later) REST service supports combining multiple requests into a single call to the service by using the OData $batch query option. 有关详细信息和代码示例链接,请参阅使用 REST API 发出批处理请求For details and links to code samples, see Make batch requests with the REST APIs.

选择要返回的字段Select fields to return

使用 $select 查询选项指定对于给定列表、列表项或实体集表示的其他 SharePoint 对象将返回哪些字段。Use the $select query option to specify which fields to return for a given list, list item, or other SharePoint object represented by an entity set. You can use to return all available fields. 可以使用 $select=* 返回所有可用字段。You can use $select=* to return all available fields.

备注

通常,如果未指定 $select 查询选项,REST 服务默认返回所有可用字段。In general, if you do not specify the $select query option, the REST service returns all available fields by default. 但是,在少数几种情况下,某些 SharePoint 对象包含检索资源极为密集的属性;为了优化 REST 服务性能,默认查询中并不包含这些属性,必须显式请求。例如,不会默认返回 SPWeb.EffectiveBasePermissions 属性,必须使用 $select 查询选项进行显式请求。However, in a few cases, some SharePoint objects include properties that are very resource intensive to retrieve; to optimize REST service performance, these properties are not included in the default query, and must be explicitly requested.For example, the SPWeb.EffectiveBasePermissions property is not returned by default, and must be explicitly requested using the $select query option.

此外,还可指定请求返回其他列表中的投影字段和查找值。In addition, you can specify that the request returns projected fields from other lists and the values of lookups. To do this, specify the field name in both the and query options. For example: 为此,请同时在 $select$expand 查询选项中指定字段名称。To do this, specify the field name in both the $select and $expand query options. 例如:For example:

http://server/site/_api/web/lists('guid')/items?$select=Title,Products/Name&$expand=Products/Name

不支持批量扩展和选择相关项。Bulk expansion and selection of related items is not supported.

选择要返回的项Select items to return

使用 $filter 查询选项来选择要返回的项。Use the $filter query option to select which items to return. SharePoint REST 服务支持的 OData 查询运算符列出了可用于 SharePoint REST 服务的筛选器查询比较选项和函数。Use the $filter query option to select which items to return. OData query operators supported in the SharePoint REST service lists the filter query comparison options and functions you can use with the SharePoint REST service.

单个值查阅字段的查询Query for single value lookup fields

单个值循环字段由 SharePoint REST 服务中两个单独的字段表示:一个字段表示实际字段值,另一个表示字段名称。您可以像对该数据类型的任何其他字段一样对循环字段值执行查询。例如,如果查询字段值为字符串,则可以在查询中使用字符串比较选项。Single value lookup fields are represented by two separate fields in the SharePoint REST service: one field representing the actual field value, and another representing the field name. You can perform queries against the lookup field value as you would any other field of that data type. For example, if the lookup field value is a string, you can use string comparison options in your query.

用户查询Query for users

在 SharePoint REST 服务中,用户用用户的友好(显示)名称,而非其别名或域\别名组合表示。因此,您必须阵对用户的友好名称构造用户查询。In the SharePoint REST service, users are represented by the user's friendly (display) name, and not their alias or domain\alias combination. Therefore, you must construct user queries against users' friendly names.

备注

不支持基于成员身份的用户查询。Membership-based user queries are not supported. 不支持通过当前用户的 ID 使用 Current 运算符执行查询。Usage of the Current operator to do queries using the ID of the current user is not supported.

多值查阅字段和用户的查询Query for multi-value lookup fields and users

由于多值循环字段作为多值字符串返回,因此无法进行查询(例如,不支持 Includes 元素或 NotIncludes 元素的等效物)。Because multi-value lookup fields are returned as a string of multiple values, there is no way to query for them (for example, the equivalent of an Includes element or NotIncludes element is not supported).

对返回的项排序Sort returned items

使用 $orderby 查询选项可指定查询返回集中项的排序方式。Use the $orderby query option to specify how to sort the items in your query return set. 若要按多个字段排序,请指定一个以逗号分隔的字段列表。To sort by multiple fields, specify a comma-separated list of fields. 也可通过向查询附加 ascdesc 关键字来指定按升序还是降序对项进行排序。Use the $orderby query option to specify how to sort the items in your query return set. To sort by multiple fields, specify a comma-separated list of fields. You can also specify whether to sort the items in ascending or descending order by appending the asc or desc keyword to your query.

对返回的项进行分页Page through returned items

使用 $top$skiptoken 查询选项可选择通过其他方式由查询返回的项的子集。Use the $top and $skiptoken query options to select a subset of the items that would otherwise be returned by your query.

备注

$skip 查询选项不适用于查询 SharePoint 列表项。The $skip query option does not work with queries for SharePoint list items.

通过 $top 选项,可选择要返回的返回集的前 n 个项。The $top option enables you to select the first n items of the return set for return. For example, the following URI requests that only the first ten items in the prospective return set actually be returned: 例如,以下 URI 请求仅返回预期返回集中的前十个项:The option enables you to select the first items of the return set for return. For example, the following URI requests that only the first ten items in the prospective return set actually be returned:

http://server/site/_api/web/lists('<guid>')/items$top=10

通过 $skiptoken 选项,可以跳过某些项,直至到达指定项,然后返回剩余的项。The $skiptoken option enables you to skip over items until the specified item is reached and return the rest.

$skiptoken=Paged=TRUE%26p_ID=5

备注

使用这些查询选项时,需考虑在 OData 中按顺序分页。When using these query options, take into account that paging in OData is ordinal. 例如,假设要实现“下一页”按钮以显示 SharePoint 列表项。For example, suppose you are implementing a next page button to display SharePoint list items. 使用 REST 服务,使单击按钮时返回项 1 至项 20,然后返回项 21 到项 40,以此类推。You use the REST service to enable the button to return items 1 through 20 when clicked, and then items 21 through 40, and so on. 但是,假设另一个用户在多次单击“下一页”按钮之间删除项 4 和项 18。However, suppose another user deletes items 4 and 18 between clicks of the next button. 在这种情况下,将重置剩余项的序号位置,实际上显示项 21 到项 40 将跳过两项。In such a case, the ordinal positioning of the remaining items is reset, and displaying items 21 through 40 actually skips over two items.

SharePoint REST 服务支持的 OData 查询运算符OData query operators supported in the SharePoint REST service

支持Supported 不支持Not supported
数字比较 Lt Le Gt Ge Eq NeNumeric comparisons Lt Le Gt Ge Eq Ne 算术运算符(Add、Sub、Mul、Div、Mod)Arithmetic operators (Add, Sub, Mul, Div, Mod)
基本数学函数(round、floor、ceiling)Basic math functions (round, floor, ceiling)
字符串比较 startsWith substringof Eq NeString comparisons startsWith substringof Eq Ne endsWith replace substring tolower toupper trim concatendsWith replace substring tolower toupper trim concat
日期和时间函数 day() month() year() hour() minute() second()Date and time functions day() month() year() hour() minute() second() DateTimeRangesOverlap 运算符DateTimeRangesOverlap operator
关于日期时间是否属于周期性日期时间模式的查询Querying as to whether a date time falls inside a recurrent date time pattern

下图显示支持的 OData 查询选项。The figure below shows the supported OData query options.

支持的 OData 查询选项Supported OData query options

SharePoint REST 服务查询选项语法


另请参阅See also