Abfrageausdrücke (WCF Data Services)
Mit Abfrageausdrücken können Sie herkömmliche Abfragevorgänge für Ressourcen ausführen, z. B. Filtern, Sortieren und Paging.Abfrageausdrücke bestehen aus Abfrageoptionen, Abfrageoperatoren und Abfragefunktionen.Abfrageoptionen definieren Vorgänge für die zurückgegebene Ressource, z. B. Filtern oder das Sortieren.Der folgende URI (der auf dem Datendienst Schnellstart basiert) gibt z. B. alle Customers-Entitäten zurück, bei denen die City-Eigenschaft den Wert London enthält.
https://localhost:12345/Northwind.svc/Customers?$filter=City eq 'London'
Systemdefinierten Abfrageoptionen wird das Dollarzeichen ($) vorangestellt.In der folgenden Tabelle werden alle Systemabfrageoptionen beschrieben, die WCF Data Services unterstützt:
Abfrageoption |
Beschreibung |
|---|---|
$expand |
Weist den Dienst an, Mengen verknüpfter Entitäten zusammen mit der adressierten Entität in einer einzelnen Antwort zurückzugeben.Sie können mehrere verknüpfte Mengen angeben, indem Sie sie durch Kommas trennen.Beispielsweise gibt der folgende URI in einer Antwort sowohl die verknüpfte Customer-Entität als auch die verknüpfte Detail-Entität für die angegebene Bestellung zurück. https://localhost:12345/Northwind.svc/Orders(10248)?$expand=Customers,Order_Details Detaillierte Optionssyntax finden Sie unter 2.2.3.6.1.3 Expand System Query Option ($expand) im Dokument "Atom Publishing Protocol: Data Services URI and Payload Extensions" (in englischer Sprache). |
$filter |
Weist den Dienst an, die zurückgegebene Menge mit Abfrageoperatoren und Funktionen zu filtern.Der folgende URI gibt beispielsweise die Menge aller Customers-Entitäten zurück, bei denen die Country-Eigenschaft den Wert USA enthält. https://localhost:12345/Northwind.svc/Customers?$filter=Country eq 'USA' Detaillierte Optionssyntax finden Sie unter 2.2.3.6.1.4 Filter System Query Option ($filter) im Dokument "Atom Publishing Protocol: Data Services URI and Payload Extensions" (in englischer Sprache). |
$inlinecount |
Weist den Dienst an, die Anzahl aller von einem URI zurückgegebenen Entitäten einzuschließen, wenn der Wert allpages angegeben wird.Diese Anzahl wird in einer separaten Abfrage ausgeführt, und der zurückgegebene Wert ist unabhängig von definierten Größenbeschränkungen der Seite.Der folgende URI gibt beispielsweise den Wert 13 in einem count-Element zusammen mit den angeforderten Customers-Entitäten zurück. https://localhost:12345/Northwind.svc/Customers?$filter=Country%20eq%20'USA'&$inlinecount=allpages Die ausführliche Optionssyntax finden Sie unter 2.2.3.6.1.10 im Dokument "Atom Publishing Protocol: Data Services URI and Payload Extensions" (in englischer Sprache). |
$orderby |
Weist den Dienst an, die zurückgegebenen Entitäten mit Abfrageoperatoren zu sortieren.Der folgende URI sortiert z. B. die zurückgegebenen Customers-Entitäten von Z bis A nach dem Wert derContactName-Eigenschaft. https://localhost:12345/Northwind.svc/Customers?$orderby=ContactName desc Diese Option kann auch die zurückgegebene Menge filtern.Der folgende URI gibt beispielsweise nur die Customers-Entitäten zurück, die nicht in den USA ansässig sind, und sortiert das Ergebnis nach dem Wert der Country-Eigenschaft. https://localhost:12345/Northwind.svc/Customers?$orderby=Country ne 'USA' asc Die ausführliche Optionssyntax finden Sie unter 2.2.3.6.1.6 im Dokument "Atom Publishing Protocol: Data Services URI and Payload Extensions" (in englischer Sprache). |
$select |
Weist den Dienst an, die zurückgegebenen Eigenschaften nur auf die Eigenschaften in einer angegebenen Projektion zu beschränken.Sie können die vom Datendienst zurückgegebene Datenmenge mit $select reduzieren.Der folgende URI gibt beispielsweise den OrderID-Wert für die ausgewählte Order-Entität zusammen mit einem Link zurück, der die Menge verknüpfter Order_Details-Entitäten zurückgibt. https://localhost:12345/Northwind.svc/Orders(10643)?$select=OrderID,Order_Details Die ausführliche Optionssyntax finden Sie unter 2.2.3.6.1.11 im Dokument "Atom Publishing Protocol: Data Services URI and Payload Extensions" (in englischer Sprache). |
$skip |
Weist den Dienst an, am Anfang einer Menge eine angegebene Anzahl von Entitäten zu überspringen.Sie können $top mit $skip für das Paging von Daten verwenden.Beispielsweise gibt der folgende URI die Ressourcen 51 bis 60 aus dem Ergebnis aller Customers-Entitäten zurück. https://localhost:12345/Northwind.svc/Customers?$top=10&$skip=50 Detaillierte Optionssyntax finden Sie unter 2.2.3.6.1.7 Skip System Query Option ($skip) im Dokument "Atom Publishing Protocol: Data Services URI and Payload Extensions" (in englischer Sprache). |
$skiptoken |
Weist den Dienst an, die nächste Seite von Ergebnissen zurückzugeben, wenn Serverpaging aktiviert ist.Weitere Informationen finden Sie unter Konfigurieren des Datendiensts (WCF Data Services).Detaillierte Optionssyntax finden Sie unter 2.2.3.6.1.9 Token System Query Option ($ im Dokument "Atom Publishing Protocol: Data Services URI and Payload Extensions" (in englischer Sprache). |
$top |
Weist den Dienst an, eine angegebene Anzahl von Entitäten in einer Menge zurückzugeben.Sie können $skip mit $top für das Paging von Daten verwenden.Beispielsweise gibt der folgende URI die Ressourcen 50 bis 60 aus dem Ergebnis aller Customers-Entitäten zurück. https://localhost:12345/Northwind.svc/Customers?$top=10&$skip=50 Detaillierte Optionssyntax finden Sie unter 2.2.3.6.1.8 Top System Query Option ($top) im Dokument "Atom Publishing Protocol: Data Services URI and Payload Extensions" (in englischer Sprache). |
Weitere Informationen zur Anwendung dieser Abfrageoptionen auf verschiedene Typen von Ressourcen finden Sie unter 2.2.3.6.1 System Query Options im Dokument "Atom Publishing Protocol: Data Services URI and Payload Extensions" (in englischer Sprache).
Abfrageoperatoren ermöglichen Ihnen die Verwendung von logischen, arithmetischen und Vergleichsoperationen innerhalb der $filter-Option und der $orderby-Option.Der folgende URI gibt z. B. alle Bestellungen zurück, bei denen die Postleitzahl nicht auf 100 endet:
https://localhost:12345/Northwind.svc/Orders?$filter=not endswith(ShipPostalCode,'100')
Die vollständige Liste der Operatoren finden Sie unter Abfrageoperatoren (WCF Data Services).
Abfragefunktionen ermöglichen Ihnen die Ausführung vordefinierter Funktionen in der $filter-Option.Die vollständige Liste der Funktionen finden Sie unter Abfragefunktionen (WCF Data Services).
Überlegungen zu Abfrageausdrücken
Die folgenden allgemeinen Überlegungen gelten für Abfrageausdrücke:
Wenn ein Datendienst in einem URI Abfrageoptionen anwendet, erfolgt dies in der folgenden Reihenfolge:
$filter
$inlinecount
$orderby
$skiptoken
$skip
$top
$select
$expand
Weitere Informationen finden Sie unter 2.2.3.6.1.2 Evaluating System Query Options im Dokument "Atom Publishing Protocol: Data Services URI and Payload Extensions" (in englischer Sprache).
Abfrageausdrücke werden sowohl für Entitätenmengen als auch Dienstvorgänge unterstützt.
Jede Abfrageoption kann in einer Abfragezeichenfolge enthalten sein, unabhängig davon, ob die Zeichenfolge bereits andere Optionen enthält.
In Abfrageoptionsnamen und -werten wird die Groß-/Kleinschreibung berücksichtigt.
In einer Abfragezeichenfolge eines Anforderungs-URI darf eine bestimmte Abfrageoption nur einmal verwendet werden.
Alle bei der Verarbeitung gefundenen syntaktischen und semantischen Fehler werden mit dem Antwortcode "400 Bad Request" behandelt.
Vergleiche und Operationen für Mengen werden von Abfrageoptionen nicht unterstützt.Beispiel: $filter=Orders/Name eq 'Name' ist ungültig, wenn Orders eine Menge darstellt. $filter=Order/Name eq 'Name' ist hingegen gültig, wenn Order eine einzelne Entität darstellt.
Da $inlinecount als von der Abfrage, die die Datenelemente zurückgibt, getrennte Abfrage ausgeführt wird, ist es möglich, dass der zurückgegebene Wert die tatsächliche Anzahl von zurückgegebenen Elementen nicht widerspiegelt.Dies kann der Fall sein, wenn eine Ressource innnerhalb des Zeitraums zwischen der Ausführung von Daten- und Anzahlabfrage eingefügt oder gelöscht wird.
Wenn Sie benutzerdefinierte Atom Publishing Protocol (AtomPub)-Feeds definieren, müssen Sie sicherstellen, dass alle Entitätseigenschaften, die über definierte benutzerdefinierte Zuordnungen verfügen, in der Projektion enthalten sind, die mit dem $select-Ausdruck definiert wird.Wenn eine zugeordnete Entitätseigenschaft nicht in der Projektion enthalten ist, könnten Datenverluste auftreten.Weitere Informationen finden Sie unter Atom-Feedsanpassung (WCF Data Services) .
Weitere Informationen finden Sie unter 2.2.3.6 Query Options im Dokument "Atom Publishing Protocol: Data Services URI and Payload Extensions" (in englischer Sprache).