Verwenden von OData-Abfragevorgängen in SharePoint REST-AnforderungenUse OData query operations in SharePoint REST requests

Bevor Sie beginnenBefore you start

Der SharePoint REST-Dienst unterstütz eine Reihe von OData-Abfragezeichenfolgeoperatoren, mit denen SIe die angeforderten Daten auswählen, filtern und ordnen können.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.

Tipp

Der SharePoint Online-REST-Dienst (sowie der REST-Dienst von lokalem SharePoint 2016 und höher) unterstützt die Kombination mehrerer Anforderungen in einem einzelnen Dienstaufruf mithilfe der OData-Abfrageoption $batch. Einzelheiten und Links zu Codebeispielen finden Sie unter Erstellen von Batchanforderungen mit den REST-APIs.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. For details and links to code samples, see Make batch requests with the REST APIs.

Auswählen der Felder, die zurückgegeben werden sollenSelect fields to return

Verwenden Sie die Abfrageoption $select, um anzugeben, welche Felder für eine bestimmte Liste, ein Listenelement oder ein anderes, durch eine Entitätenmenge dargestelltes SharePoint-Objekt zurückgegeben werden sollen. Sie können $select=* verwenden, um alle verfügbaren Felder zurückzugeben.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 $select=* to return all available fields.

Hinweis

In general, if you do not specify the $select query option, the REST service returns all available fields by default. 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 by using the $select query option.In general, if you do not specify the $select query option, the REST service returns all available fields by default. 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 by using the $select query option.

Darüber hinaus können Sie angeben, dass die Anforderung projizierte Felder aus anderen Listen und die Werte von Suchvorgängen zurückgeben soll. Geben Sie hierzu in den beiden Abfrageoptionen $select und $expand den Feldnamen an. Beispiel: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 $select and $expand query options. For example:

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

Massenerweiterung und die Auswahl damit zusammenhängender Elemente wird nicht unterstützt.Bulk expansion and selection of related items is not supported.

Auswählen der Elemente, die zurückgegeben werden sollenSelect items to return

Verwenden Sie die Abfrageoption $filter, um auszuwählen, welche Elemente zurückgegeben werden sollen. Unter Vom SharePoint-REST-Dienst unterstützte OData-Abfrageoperatoren sind die Optionen und Funktionen zum Vergleich der Filterabfragen aufgeführt, die Sie im SharePoint REST-Dienst verwenden können.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.

Abfrage für Einzelwert-SuchfelderQuery for single value lookup fields

Einzelwert-Suchfelder werden beim SharePoint REST-Dienst als zwei separate Felder dargestellt: ein Feld für den tatsächlichen Feldwert und ein weiteres für den Feldnamen. Sie können Abfragen des Suchfeldwerts durchführen wie bei jedem anderen Feld dieses Datentyps. Wenn beispielsweise der Wert des Suchfelds eine Zeichenfolge ist, können Sie die Vergleichsoptionen für Zeichenfolgen in Ihrer Abfrage verwenden.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.

Abfrage von BenutzernQuery for users

Beim SharePoint REST-Dienst werden die Benutzer durch ihren Anzeigennamen repräsentiert und nicht ihrem Alias oder ihrer Domäne\Alias-Kombination. Daher müssen Sie sich bei Benutzerabfragen nach den Anzeigenamen richten.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.

Hinweis

Membership-based user queries are not supported. Usage of the Current operator to do queries using the ID of the current user is not supported.Membership-based user queries are not supported. Usage of the Current operator to do queries using the ID of the current user is not supported.

Abfrage für Suchfelder und Benutzer mit mehreren WertenQuery for multi-value lookup fields and users

Da Suchfelder mit mehreren Werten als eine Zeichenfolge mehrerer Werte zurückgegeben werden, ist es nicht möglich, sie abzufragen (z. B. wird das Äquivalent eines Includes-Elements oder NotIncludes-Elements nicht unterstützt).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).

Sortieren der zurückgegebenen ElementeSort returned items

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.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.

Unterteilen der zurückgegebenen ElementePage through returned items

Verwenden Sie die Abfrageoptionen $top und $skiptoken, um eine Teilmenge von Elementen auszuwählen, die nicht von der Abfrage zurückgegeben werden sollen.Use the $top and $skiptoken query options to select a subset of the items that would otherwise be returned by your query.

Hinweis

Die Abfrageoption $skip funktioniert nicht bei Abfragen für SharePoint-Listenelemente.The $skip query option does not work with queries for SharePoint list items.

Die Option $top ermöglicht Ihnen, die ersten n Elemente des Rückgabesatzes für die Rückgabe auszuwählen. Die folgende URI fordert beispielsweise an, dass nur die ersten zehn Elemente des potenziellen Rückgabesatzes tatsächlich zurückgegeben werden: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:

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

Mit der Option „$skiptoken“ können Sie Elemente bis zum angegebenen Element überspringen und den Rest zurückgeben.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

Hinweis

When using these query options, take into account that paging in OData is ordinal. For example, suppose you are implementing a next page button to display SharePoint list items. 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. However, suppose another user deletes items 4 and 18 between clicks of the next button. In such a case, the ordinal positioning of the remaining items is reset, and displaying items 21 through 40 actually skips over two items.When using these query options, take into account that paging in OData is ordinal. For example, suppose you are implementing a next page button to display SharePoint list items. 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. However, suppose another user deletes items 4 and 18 between clicks of the next button. In such a case, the ordinal positioning of the remaining items is reset, and displaying items 21 through 40 actually skips over two items.

Vom SharePoint REST-Dienst unterstützte OData-AbfrageoperatorenOData query operators supported in the SharePoint REST service

UnterstütztSupported Nicht unterstütztNot supported
Numerische Vergleiche Lt Le Gt Ge Eq NeNumeric comparisons Lt Le Gt Ge Eq Ne Arithmetische Operatoren (Add, Sub, Mul, Div, Mod)Arithmetic operators (Add, Sub, Mul, Div, Mod)
Grundlegende mathematische Funktionen (Runden, Untergrenze, Obergrenze)Basic math functions (round, floor, ceiling)
String-Vergleiche startsWith substringof Eq NeString comparisons startsWith substringof Eq Ne endsWith replace substring tolower toupper trim concatendsWith replace substring tolower toupper trim concat
Datums- und Uhrzeitfunktionen day() month() year() hour() minute() second()Date and time functions day() month() year() hour() minute() second() Operator „DateTimeRangesOverlap“DateTimeRangesOverlap operator
Abfrage, ob Datum-Zeit in ein wiederkehrendes Datum-Zeit-Muster fälltQuerying as to whether a date time falls inside a recurrent date time pattern

Die folgende Abbildung zeigt unterstützte OData-Abfrageoptionen.The following figure shows the supported OData query options.

Unterstützte OData-AbfrageoptionenSupported OData query options

Abfrageoptionssyntax des SharePoint REST-Diensts


Siehe auchSee also