Filtern von Zeilen mit OData

Artikel
08/05/2024

Verwenden Sie die $filter Abfrageoption , um eine Ressourcensammlung zu filtern.

Dataverse wertet jede Ressource in der Sammlung mit dem Ausdruckssatz für $filter aus. Nur Datensätze, bei denen der Ausdruck zu true ausgewertet wird, werden in der Antwort zurückgegeben. Datensätze werden nicht zurückgegeben, wenn der Ausdruck zu false oder null ausgewertet wird oder wenn der Benutzer keinen Lesezugriff auf den Datensatz hat.

Die folgende Tabelle beschreibt die Operatoren und Funktionen, die Sie in $filter-Ausdrücken verwenden können.

	Beschreibung	Weitere Informationen
Vergleichsoperatoren	Verwenden Sie die `eq`,`ne`,`gt`,`ge`,`lt`, Und `le` Operatoren zum Vergleichen einer Eigenschaft und eines Werts.	Vergleichsoperatoren
Logische Operatoren	Verwenden von `and`, `or`, und `not`, um komplexere Ausdrücke zu erstellen.	Logische Operatoren
Gruppierungsoperatoren	Verwenden Sie Klammern: `()`, um die Priorität bei der Auswertung eines komplexen Ausdrucks anzugeben.	Gruppierungsoperatoren
OData-Abfragefunktionen verwenden	Werten Sie Zeichenfolgenwerte mit `contains`, `endswith` und `startswith` Funktionen aus.	OData-Abfragefunktionen verwenden
Dataverse Abfragefunktionen	Verwenden Sie mehr als 60 spezialisierte Funktionen, die für Geschäftsanwendungen entwickelt wurden.	Dataverse Abfragefunktionen
Lambda-Ausdrücke	Erstellen Sie Ausdrücke basierend auf Werten verwandter Sammlungen.	Filtern Sie anhand von Werten verwandter Sammlungen

Vergleichsoperatoren

Die folgende Tabelle beschreibt die Operatoren, die Sie verwenden können, um eine Eigenschaft und einen Wert zu vergleichen.

Operator	Beschreibung	Beispiel
`eq`	Equal	`$filter=revenue eq 100000`
`ne`	Ungleich	`$filter=revenue ne 100000`
`gt`	Größer als	`$filter=revenue gt 100000`
`ge`	Größer als oder gleich	`$filter=revenue ge 100000`
`lt`	Kleiner als	`$filter=revenue lt 100000`
`le`	Kleiner oder gleich	`$filter=revenue le 100000`

Vergleich von Spalten

Sie können Vergleichsoperatoren verwenden, um Eigenschaftswerte in derselben Zeile zu vergleichen. Nur Vergleichsoperatoren können verwendet werden, um Werte in derselben Zeile zu vergleichen, und die Spaltentypen müssen übereinstimmen. Die folgende Abfrage gibt z.B. alle Kontakte zurück, bei denen firstname gleich lastname ist:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname&$filter=firstname eq lastname

Logische Operatoren

Die folgende Tabelle beschreibt die logischen Operatoren, die Sie verwenden können, um komplexere Ausdrücke zu erstellen.

Operator	Beschreibung	Beispiel
`and`	Logisch und	`$filter=revenue lt 100000 and revenue gt 2000`
`or`	Logisch oder	`$filter=contains(name,'(sample)') or contains(name,'test')`
`not`	Logische Negation	`$filter=not contains(name,'sample')`

Gruppierungsoperatoren

Verwenden Sie Klammern () mit logischen Operatoren, um die Priorität für die Auswertung eines komplexen Ausdrucks anzugeben. Beispiel:

$filter=(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Dataverse-Abfragefunktionen

Verwenden Sie mehr als 60 spezialisierte Funktionen, die für Geschäftsanwendungen entwickelt wurden. Diese Funktionen bieten besondere Funktionalitäten, wie in der folgenden Tabelle beschrieben.

Gruppieren	Funktionen
Datumsangaben	InFiscalPeriod, InFiscalPeriodAndYear, InFiscalYear, InOrAfterFiscalPeriodAndYear, InOrBeforeFiscalPeriodAndYear, Last7Days, LastFiscalPeriod, LastFiscalYear, LastMonth, LastWeek, LastXDays, LastXFiscalPeriods, LastXFiscalYears, LastXHours, LastXMonths, LastXWeeks, LastXYears, LastYear, Next7Days, NextFiscalPeriod, NextFiscalYear, NextMonth, NextWeek, NextXDays, NextXFiscalPeriods, NextXFiscalYears, NextXHours, NextXMonths, NextXWeeks, NextXYears, NextYear, OlderThanXDays, OlderThanXHours, OlderThanXMinutes, OlderThanXMonths, OlderThanXWeeks, OlderThanXYears, On, OnOrAfter, OnOrBefore, ThisFiscalPeriod, ThisFiscalYear, ThisMonth, ThisWeek, ThisYear, Today, Tomorrow, Yesterday
ID-Werte	EqualBusinessId, EqualUserId, NotEqualBusinessId, NotEqualUserId
Hierarchie	Above, AboveOrEqual, EqualUserOrUserHierarchy, EqualUserOrUserHierarchyAndTeams, EqualUserOrUserTeams, EqualUserTeams, NotUnder, Under, UnderOrEqual Weitere Informationen: Hierarchische Daten abfragen
Auswahlspalten	ContainValues, DoesNotContainValues Weitere Informationen: Daten aus Auswahlmöglichkeiten abfragen
Zwischen	Between, NotBetween
In	In, NotIn
Sprache	EqualUserLanguage

Hinweis

Die Funktion Enthält ist für die Verwendung mit Spalten gedacht, die über eine Volltextindizierung verfügen. Nur die Tabelle Dynamics 365 KBArticle (Artikel) hat Spalten mit Volltextindizierung. Verwenden Sie stattdessen die Funktion OData contains.

Die Web API Query Function Reference enthält die vollständige Liste. Jeder Artikel enthält ein Syntaxbeispiel, das Sie kopieren können.

Sie müssen den vollständig qualifizierten Namen der Funktion verwenden und den Dienst-Namespace (Microsoft.Dynamics.CRM) an den Namen der Funktion anhängen.

Jede Funktion hat einen PropertyName-Parameter, der die zu bewertende Eigenschaft angibt. Die Funktion kann mehr Parameter haben, z. B. PropertyValue, PropertyValues oder PropertyValue1 und PropertyValue2. Wenn diese Parameter vorhanden sind, müssen Sie einen oder mehrere Werte angeben, um sie mit dem PropertyName -Parameter zu vergleichen.

Das folgende Beispiel zeigt die Verwendung der Between-Funktion für die Suche nach Konten mit 5 bis 2.000 Mitarbeitern.

GET [Organization URI]/api/data/v9.2/accounts?$select=name,numberofemployees
&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])

Filtern Sie mithilfe von Zeichenfolgenwerten

Beachten Sie die folgenden Punkte, wenn Sie nach Zeichenfolgen filtern:

Alle Filter für String-Werte sind unabhängig von der Groß-/Kleinschreibung.
Sie müssen Sonderzeichen in Filterkriterien URL-kodieren. Weitere Informationen: URL-Codierung von Sonderzeichen
Sie können Platzhalterzeichen verwenden, vermeiden Sie jedoch deren falsche Verwendung. Mehr Informationen: Verwenden von Platzhalterzeichen
Sie können OData Abfragefunktionen verwenden: contains, startswith, und endswith. Weitere Informationen: OData Abragefunktionen verwenden
Sie müssen einfache Anführungszeichen verwalten, wenn Sie Filter verwenden, die eine Reihe von Zeichenfolgen akzeptieren. Weitere Informationen: Verwalten von Einzelangeboten

URL-Codierung von Sonderzeichen

Wenn die Zeichenfolge, die Sie als Wert in einer Filterfunktion verwenden, ein Sonderzeichen enthält, müssen Sie es per URL codieren. Wenn Sie beispielsweise diese Funktion verwenden: contains(name,'+123'), wird es nicht funktionieren, weil + ein Zeichen ist, das nicht in eine URL eingefügt werden kann. Wenn Sie die Zeichenfolge per URL codieren, wird sie zu contains(name,'%2B123') und Sie erhalten Ergebnisse, bei denen der Spaltenwert +123 enthält.

Die folgende Tabelle zeigt die URL-codierten Werte für häufige Sonderzeichen.

Sonder- zeichen	URL-codiertes zeichen
`$`	`%24`
`&`	`%26`
`+`	`%2B`
`,`	`%2C`
`/`	`%2F`
`:`	`%3A`
`;`	`%3B`
`=`	`%3D`
`?`	`%3F`
`@`	`%40`

Platzhalterzeichen verwenden

Beim Erstellen von Filtern mit Zeichenfolgen können Sie die folgenden Platzhalterzeichen anwenden:

Zeichen	Beschreibung	T-SQL Dokumentation und Beispiele
`%`	Stimmt mit einer beliebigen Zeichenfolge aus null oder mehr Zeichen überein. Dieses Platzhalterzeichen kann entweder als Präfix oder als Suffix verwendet werden.	Prozentzeichen (Platzhalter – Abzugleichende Zeichen) (Transact-SQL)
`_`	Verwenden Sie den Unterstrich, um ein beliebiges einzelnes Zeichen in einem Zeichenfolgenvergleichsvorgang abzugleichen, der einen Musterabgleich beinhaltet.	_ (Platzhalter – Übereinstimmung mit einem Zeichen) (Transact-SQL)
`[]`	Stimmt mit jedem einzelnen Zeichen innerhalb des angegebenen Bereichs oder Satzes überein, der in Klammern angegeben ist.	[ ] (Platzhalter - Übereinstimmende Zeichen) (Transact-SQL)
`[^]`	Stimmt mit jedem einzelnen Zeichen nicht innerhalb des angegebenen Bereichs oder Satzes überein, der in eckigen Klammern angegeben ist.	[^] (Platzhalter - Nicht Übereinstimmende Zeichen) (Transact-SQL)

Weitere Informationen: Platzhalterzeichen in Bedingungen für Zeichenfolgenwerte verwenden

Führende Platzhalter werden nicht unterstützt

Es ist wichtig, am Anfang keine wilden Karten zu verwenden, da diese nicht unterstützt werden. Abfragen, die diese Anti-Patterns verwenden, führen zu Leistungsproblemen, da die Abfragen nicht optimiert werden können. Hier einige Beispiele für führende Platzhalter:

startswith(name,'%value')
endswith(name,'value%')

Erfahren Sie mehr über Fehler, die bei der Verwendung führender Platzhalter zurückgegeben werden

OData-Abfragefunktionen verwenden

Die folgende Tabelle beschreibt die OData-Abfragefunktionen, die Sie zum Filtern von Zeichenfolgen verwenden können:

Funktion	Beispiel
`contains`	`$filter=contains(name,'(sample)')`
`endswith`	`$filter=endswith(name,'Inc.')`
`startswith`	`$filter=startswith(name,'a')`

Sie können diese Funktionen mit dem logischen Operator not verwenden, um das Ergebnis zu negieren.

Einzelangebote verwalten

Einige Filter akzeptieren ein Array von Zeichenfolgen, wie z.B. die Funktion In Query. Wenn Sie in diesen Filtern Werte angeben, die einfache Anführungszeichen oder Apostrophe enthalten, wie z.B. O'Brian oder Men's clothes, müssen Sie die Werte in doppelte Anführungszeichen setzen, zum Beispiel:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
&$filter=Microsoft.Dynamics.CRM.In(PropertyName=@p1,PropertyValues=@p2)
&@p1='lastname'
&@p2=["OBrian","OBryan","O'Brian","O'Bryan"]

Wenn Sie das nicht tun, erhalten Sie die folgende Fehlermeldung: Invalid JSON. A comma character ',' was expected in scope 'Array'. Every two elements in an array and properties of an object must be separated by commas.

Wenn sich der Filter auf einen einzelnen Wert bezieht, ersetzen Sie das einfache Anführungszeichen durch zwei aufeinanderfolgende einfache Anführungszeichen, zum Beispiel:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
&$filter=lastname eq 'O''Bryan'

Wenn Sie das nicht tun, erhalten Sie eine Fehlermeldung wie diese: There is an unterminated literal at position 21 in 'lastname eq 'O'Bryan''.

Sie können zurückgegebene Zeilen basierend auf Werten in verknüpften Tabellen filtern. Wie Sie filtern, hängt von der Art der Beziehung ab.

Filtern nach Nachschlageeigenschaften

Bei Eins-zu-viele-Beziehungen liefert eine gefilterte Sammlung dieselben Ergebnisse wie die Verwendung einer eq $filter auf der Lookup-Eigenschaft für die Beziehung. Beispielsweise diese gefilterte Sammlung:

GET [Organization URI]/api/data/v9.2/systemusers(<systemuserid value>)/user_accounts?$select=name

Ist dasselbe wie dieser Filter für eine Nachschlageeigenschaft.

GET [Organization URI]/api/data/v9.2/accounts?$filter=_owninguser_value eq <systemuserid value>&$select=name

Filtern Sie mithilfe von Eigenschaftswerten der Nachschlagespalte

Sie können basierend auf Werten in einzelwertigen Navigationseigenschaften filtern, die Nachschlagespalten darstellen. Dieses Muster verwenden:

<single-valued navigation property>/<property name>

Das folgende Beispiel gibt Datensätze von Konten basierend auf dem Wert der Spalte primarycontactid/fullname zurück:

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts?$filter=primarycontactid/fullname eq 'Susanna Stubberod (sample)'
&$select=name,_primarycontactid_value
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Antwort:

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,_primarycontactid_value)",
    "value": [
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}

Sie können auch Werte weiter oben in der Hierarchie der einzelwertigen Navigationseigenschaften vergleichen.

Das folgende Beispiel gibt das erste Konto zurück, bei dem der Datensatz des Kontakts die primarycontactid darstellt, wobei 'Systemadministrator' den Datensatz erstellt hat, unter Verwendung der primarycontactid/createdby/fullname in der $filter.

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts?$filter=primarycontactid/createdby/fullname eq 'System Administrator'
&$select=name,_primarycontactid_value
&$expand=primarycontactid(
$select=fullname,_createdby_value;
$expand=createdby($select=fullname))
&$top=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Antwort:

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,_primarycontactid_value,primarycontactid(fullname,_createdby_value,createdby(fullname)))",
    "value": [
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "fullname": "Susanna Stubberod (sample)",
                "_createdby_value@OData.Community.Display.V1.FormattedValue": "System Administrator",
                "_createdby_value": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "createdby": {
                    "fullname": "System Administrator",
                    "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                    "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                }
            }
        }
    ]
}

Verwenden Sie die Lambda-Operatoren any und all, um Werte in einer Sammlung auszuwerten und die Ergebnisse zu filtern.

any: Gibt true zurück, wenn der angewendete Ausdruck für ein beliebiges Mitglied der Sammlung wahr ist; andernfalls gibt er false zurück.
- Der any-Operator ohne Argument gibt true zurück, wenn die Sammlung nicht leer ist.
all: Gibt „Wahr“ zurück, wenn der angewandte Ausdruck für alle Mitglieder der Sammlung wahr ist; andernfalls wird „Falsch“ zurückgegeben.

Die Syntax sieht so aus:

<collection>/[any | all](o:<expression to evaluate>)

In diesem Fall ist o die Variable, die Elemente in der Sammlung darstellt. Die Konvention besteht darin, den ersten Buchstaben des Typs zu verwenden. Verwenden Sie in dem Ausdruck o/<property or collection name>, um auf eine Eigenschaft oder Sammlung eines bestimmten Artikels zu verweisen.

Sie können Bedingungen für mehrere sammlungswertige Navigationseigenschaften und verschachtelte Sammlungen einschließen. Sie können keine Bedingungen in Navigationseigenschaften mit Sammlungswert einfügen, die in ein Suchfeld verschachtelt sind. Zum Beispiel: $filter=primarycontactid/new_contact_account/any(a:a/accountid eq '{GUID}') wird nicht unterstützt.

Weitere Informationen: Lambda-Operatoren unter oData.org verwenden

Beispiele für Lambda-Operatoren

Das folgende Beispiel ruft alle Konto Datensätze ab, die mindestens eine E-Mail mit „sometext“ im Betreff haben:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(e:contains(e/subject,'sometext'))
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Das folgende Beispiel ruft alle Konto Datensätze ab, bei denen alle zugehörigen Aufgaben geschlossen sind:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Tasks/all(t:t/statecode eq 1)
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Das folgende Beispiel ruft alle Konto Datensätze ab, die mindestens eine E-Mail mit „sometext“ im Betreff haben und deren Statuscode aktiv ist:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(e:contains(e/subject,'sometext') and 
e/statecode eq 0)
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Das folgende Beispiel erstellt eine verschachtelte Abfrage mit den Operatoren any und all:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=(contact_customer_accounts/any(c:c/jobtitle eq 'jobtitle' and 
c/opportunity_customer_contacts/any(o:o/description ne 'N/A'))) and 
endswith(name,'Inc.')
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Grenzwerte für Bedingungen

Sie können insgesamt nicht mehr als 500 Bedingungen in eine Abfrage aufnehmen. Andernfalls wird dieser Fehler angezeigt:

Name: TooManyConditionsInQuery
Code: 0x8004430C
Nummer: -2147204340
Meldung: Number of conditions in query exceeded maximum limit.

Sie müssen die Anzahl der Bedingungen zum Ausführen der Abfrage reduzieren. Möglicherweise können Sie die Anzahl der Bedingungen reduzieren, indem Sie die Abfragefunktionen In oder NotIn verwenden, die mit Zahlen, eindeutigen Kennungen und Zeichenfolgen mit bis zu 850 Zeichen verwendet werden können.

Nächste Schritte,

Erfahren Sie, wie Sie Ergebnisse auslagern.

Seitenergebnisse

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).

Freigeben über

Filtern von Zeilen mit OData

Vergleichsoperatoren

Vergleich von Spalten

Logische Operatoren

Gruppierungsoperatoren

Dataverse-Abfragefunktionen

Filtern Sie mithilfe von Zeichenfolgenwerten

URL-Codierung von Sonderzeichen

Platzhalterzeichen verwenden

Führende Platzhalter werden nicht unterstützt

OData-Abfragefunktionen verwenden

Einzelangebote verwalten

Filtern nach Nachschlageeigenschaften

Filtern Sie mithilfe von Eigenschaftswerten der Nachschlagespalte

Beispiele für Lambda-Operatoren

Grenzwerte für Bedingungen

Nächste Schritte,

Zusätzliche Ressourcen

Freigeben über

Filtern von Zeilen mit OData

Vergleichsoperatoren

Vergleich von Spalten

Logische Operatoren

Gruppierungsoperatoren

Dataverse-Abfragefunktionen

Filtern Sie mithilfe von Zeichenfolgenwerten

URL-Codierung von Sonderzeichen

Platzhalterzeichen verwenden

Führende Platzhalter werden nicht unterstützt

OData-Abfragefunktionen verwenden

Einzelangebote verwalten

Filter basierend auf zugehörigen Datenwerten

Filtern nach Nachschlageeigenschaften

Filtern Sie mithilfe von Eigenschaftswerten der Nachschlagespalte

Filtern Sie anhand von Werten verwandter Sammlungen

Beispiele für Lambda-Operatoren

Grenzwerte für Bedingungen

Nächste Schritte,

Zusätzliche Ressourcen