Verwenden von OData-Abfragevorgängen in SharePoint REST-Anforderungen
Tipp
Bevor Sie beginnen, überprüfen Sie die folgenden Ressourcen:
Der SharePoint REST-Dienst unterstütz eine Reihe von OData-Abfragezeichenfolgeoperatoren, mit denen SIe die angeforderten Daten auswählen, filtern und ordnen können.
Tipp
Der SharePoint Online-REST-Dienst (und lokale SharePoint 2016 und höher) unterstützt das Kombinieren mehrerer Anforderungen in einem einzigen Aufruf des Diensts mithilfe der OData-Abfrageoption $batch . Einzelheiten und Links zu Codebeispielen finden Sie unter Durchführen von Batchanforderungen mit den REST-APIs.
Auswählen der Felder, die zurückgegeben werden sollen
Verwenden Sie die Abfrageoption $select , um anzugeben, welche Felder für eine bestimmte Liste, ein Listenelement oder ein anderes SharePoint-Objekt zurückgegeben werden sollen, das durch eine Entitätsmenge dargestellt wird. Sie können $select=* verwenden, um alle verfügbaren Felder zurückzugeben.
Hinweis
Wenn Sie die $select Abfrageoption nicht angeben, gibt der REST-Dienst standardmäßig alle verfügbaren Felder zurück. In einigen Fällen enthalten jedoch einige SharePoint-Objekte Eigenschaften, deren Abruf sehr ressourcenintensiv ist. Um die Leistung des REST-Diensts zu optimieren, sind diese Eigenschaften nicht in der Standardabfrage enthalten und müssen explizit angefordert werden. Beispielsweise wird die SPWeb.EffectiveBasePermissions-Eigenschaft standardmäßig nicht zurückgegeben und muss mithilfe der $select Abfrageoption explizit angefordert werden.
Sie können auch angeben, dass die Anforderung projizierte Felder aus anderen Listen und die Werte von Nachschlagevorgängen zurückgibt. Geben Sie dazu den Feldnamen in den $select Abfrageoptionen und $expand an. Beispiel:
GET https://{site_url}/_api/web/lists('{list_guid}')/items?$select=Title,Products/Name&$expand=Products/Name
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Massenerweiterung und die Auswahl damit zusammenhängender Elemente wird nicht unterstützt.
Auswählen der Elemente, die zurückgegeben werden sollen
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 Filter-, Abfrage- und Vergleichsfunktionen und Optionen aufgeführt, die Sie mit dem SharePoint REST-Dienst nutzen können.
Abfrage für Einzelwert-Suchfelder
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 für den Wert des Nachschlagefelds wie jedes andere Feld dieses Datentyps ausführen. Wenn beispielsweise der Wert des Suchfelds eine Zeichenfolge ist, können Sie die Vergleichsoptionen für Zeichenfolgen in Ihrer Abfrage verwenden.
Abfrage von Benutzern
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.
Hinweis
Mitgliedschaftsbasierte Benutzerabfragen werden nicht unterstützt Die Verwendung des Current-Operators zum Ausführen von Abfragen mit der ID des aktuellen Benutzers wird nicht unterstützt.
Abfrage für Suchfelder und Benutzer mit mehreren Werten
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).
Sortieren der zurückgegebenen Elemente
Verwenden Sie die Abfrageoption $orderby , um anzugeben, wie die Elemente in Ihrem Abfragerückgabesatz sortiert werden sollen. Um mehrere Felder zu sortieren, geben Sie eine durch Kommas getrennte Liste von Feldern an. Sie können auch angeben, ob die Elemente in auf- oder absteigender Reihenfolge sortiert werden sollen, indem Sie an Ihre Abfrage das Schlüsselwort asc oder desc anhängen.
Unterteilen der zurückgegebenen Elemente
Verwenden Sie die Abfrageoptionen $top und $skiptoken, um eine Teilmenge von Elementen auszuwählen, die nicht von der Abfrage zurückgegeben werden sollen.
Hinweis
Die Abfrageoption $skip funktioniert nicht bei Abfragen für SharePoint-Listenelemente.
Mit $top der Option können Sie die ersten n Elemente des Rückgabesatzes für die Rückgabe auswählen. Der folgende URI fordert beispielsweise an, dass nur die ersten 10 Elemente im prospektiven Rückgabesatz tatsächlich zurückgegeben werden:
GET https://{site_url}/_api/web/lists('{list_guid}')/items?$top=10`
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Mit der Abfrageoption $skiptoken können Sie Elemente bis zum angegebenen Element überspringen und den Rest zurückgeben.
GET https://{site_url}/_api/web/lists('{list_guid}')/items?$skiptoken=Paged=TRUE%26p_ID=5`
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Hinweis
Beachten Sie bei der Verwendung dieser Abfrageoptionen, dass das Unterteilen in OData ordinal ist. Nehmen Sie beispielsweise an, dass Sie eine "Nächste Seite"-Schaltfläche implementieren, um SharePoint-Listenelemente anzuzeigen. Sie verwenden den REST-Dienst, um die Schaltfläche so zu aktivieren, dass die Elemente 1 bis 20 zurückgegeben werden, wenn darauf geklickt wird, und dann die Elemente 21 bis 40 usw. Nehmen Sie jedoch an, dass ein anderer Benutzer die Elemente 4 und 18 zwischen den Klicks auf "Nächste Seite" löscht. In so einem Fall wird die ordinale Position der verbleibenden Elemente zurückgesetzt und beim Anzeigen der Elemente 21 bis 40 werden eigentlich zwei Elemente übersprungen.
Vom SharePoint REST-Dienst unterstützte OData-Abfrageoperatoren
| Unterstützt | Nicht unterstützt |
|---|---|
| Numerische Vergleiche (lt le gt ge eq ne) | Arithmetische Operatoren (add, sub, mul, div, mod) Grundlegende mathematische Funktionen (round, floor, ceiling) |
| Zeichenfolgenvergleiche startswith( {Col to query},'{string to check}' ) substringof( '{zu überprüfende Zeichenfolge}', {Spalte zur Abfrage}) eq ne |
endswith, replace, substring, tolower, toupper, trim, concat |
| Datums- und Uhrzeitfunktionen day(), month(), year(), hour(), minute(), second() | Operator „DateTimeRangesOverlap“ Abfrage, ob Datum-Zeit in ein wiederkehrendes Datum-Zeit-Muster fällt |
Die folgende Abbildung zeigt unterstützte OData-Abfrageoptionen.
Unterstützte OData-Abfrageoptionen
