Anmerkung
Der Zugriff auf diese Seite erfordert eine Genehmigung. Du kannst versuchen, dich anzumelden oder die Verzeichnisse zu wechseln.
Der Zugriff auf diese Seite erfordert eine Genehmigung. Du kannst versuchen , die Verzeichnisse zu wechseln.
Verwenden Sie die $filterOData-Abfrageoption , um eine Sammlung von Ressourcen zu filtern.
Dataverse wertet jede Ressource in der Sammlung mit dem Ausdruckssatz für $filter aus. Die Antwort enthält nur Datensätze, in denen der Ausdruck zu true ausgewertet wird. Datensätze werden nicht einbezogen, 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 für die Auswertung eines komplexen Ausdrucks anzugeben. |
Gruppierungsoperatoren |
| OData-Abfragefunktionen verwenden | Werte von Zeichenfolgen mithilfe von contains, endswithund startswith Funktionen auswerten. |
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. | Anhand von Werten verwandter Sammlungen filtern |
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. Sie können vergleichsoperatoren nur verwenden, 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 Rangfolge 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.
Notiz
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 voll qualifizierten Namen der Funktion verwenden und den Service-Namensraum (Microsoft.Dynamics.CRM) an den Namen der Funktion anhängen.
Jede Funktion verfügt über einen PropertyName Parameter, der die auszuwertende Eigenschaft angibt. Die Funktion verfügt möglicherweise über weitere Parameter, wie PropertyValue, PropertyValues, PropertyValue1 oder PropertyValue2. Wenn diese Parameter vorhanden sind, geben Sie einen Wert oder einen Wert an, der mit dem PropertyName Parameter verglichen werden soll.
Das folgende Beispiel zeigt, wie Sie mithilfe der Funktion "Zwischen" nach Konten mit zwischen 5 und 2.000 Mitarbeitern suchen.
GET [Organization URI]/api/data/v9.2/accounts?$select=name,numberofemployees
&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])
Filtern mithilfe von Zeichenfolgenwerten
Beachten Sie die folgenden Punkte, wenn Sie mithilfe von Zeichenfolgenwerten filtern:
- Alle Filter für String-Werte sind unabhängig von der Groß-/Kleinschreibung.
- Sie müssen Sonderzeichen in Filterkriterien URL-kodieren. Weitere Informationen finden Sie unter URL-Codieren von Sonderzeichen.
- Sie können Wildcardzeichen verwenden, sollten sie jedoch nicht falsch einsetzen. Weitere Informationen finden Sie unter Verwenden von Wildcardzeichen.
- Sie können OData Abfragefunktionen verwenden:
contains,startswith, undendswith. Weitere Informationen finden Sie unter Verwenden von OData-Abfragefunktionen. - Sie müssen einfache Anführungszeichen verwalten, wenn Sie Filter verwenden, die eine Reihe von Zeichenfolgen akzeptieren. Weitere Informationen finden Sie unter Verwalten einzelner Anführungszeichen.
URL-Codierung von Sonderzeichen
Wenn die Zeichenfolge, die Sie als Wert in einer Filterfunktion verwenden, ein Sonderzeichen enthält, müssen Sie sie urlcodieren. Wenn Sie z. B. diese Funktion verwenden: contains(name,'+123'), funktioniert sie nicht, da es sich um + ein Zeichen handelt, das nicht in eine URL eingeschlossen werden kann. Wenn Sie die Zeichenfolge 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
Wenn Sie Filter mithilfe von Zeichenfolgen verfassen, können Sie die folgenden Wildcardzeichen verwenden:
| Zeichen | Beschreibung | T-SQL Dokumentation und Beispiele |
|---|---|---|
% |
Stimmt mit einer beliebigen Zeichenfolge aus null oder mehr Zeichen überein. Verwenden Sie dieses Wildcardzeichen entweder als Präfix oder als Suffix. | 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) |
[] |
Entspricht einem beliebigen einzelnen Zeichen innerhalb des angegebenen Bereichs oder Sets, das Sie in Klammern angeben. | [ ] (Platzhalter - Übereinstimmende Zeichen) (Transact-SQL) |
[^] |
Entspricht jedem einzelnen Zeichen, das nicht innerhalb des Bereichs oder der Menge liegt, die Sie in den eckigen Klammern angeben. | [^] (Platzhalter - Nicht Übereinstimmende Zeichen) (Transact-SQL) |
Weitere Informationen finden Sie unter Verwenden von Wildcardzeichen in Bedingungen für Zeichenfolgenwerte.
Führende Wildcards werden nicht unterstützt.
Verwenden Sie keine führenden Wildcards, da sie nicht unterstützt werden. Abfragen, die diese Anti-Patterns verwenden, führen zu Leistungsproblemen, da die Abfragen nicht optimiert werden können. Hier sind einige Beispiele für Einzugs-Platzhalter:
startswith(name,'%value')
endswith(name,'value%')
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') |
Verwenden Sie diese Funktionen mit dem logischen Operator not , um das Ergebnis zu negieren.
Einzelangebote verwalten
Einige Filter akzeptieren ein Array von Zeichenfolgen, wie z.B. die Funktion In Query. Wenn Sie Werte in diesen Filtern angeben, die ein einfaches Anführungszeichen oder Apostroph enthalten, wie zum Beispiel O'Brian oder Men's clothes, verwenden Sie doppelte Anführungszeichen um die Werte; 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''.
Filter basierend auf zugehörigen Datenwerten
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.
Filter für die Suche von Eigenschaften
Für 1:n-Beziehungen gibt eine gefilterte Auflistung die gleichen Ergebnisse zurück wie die Verwendung eines 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 identisch mit diesem Filter für eine Sucheigenschaft.
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 auf Grundlage von Werten in einwertiger Navigationseigenschaftswerten filtern, die 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 einwertigen Navigationseigenschaften vergleichen.
Das folgende Beispiel gibt das erste Konto zurück, bei dem der Kontaktdatensatz das primarycontactid darstellt und der 'Systemadministrator' den Datensatz erstellt hat, indem primarycontactid/createdby/fullname im $filter verwendet wird.
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"
}
}
}
]
}
Filtern Sie anhand von Werten verwandter Sammlungen
Verwenden Sie die Lambda-Operatorenany und all, um Werte in einer Sammlung auszuwerten und die Ergebnisse zu filtern.
any: Gibttruezurück, wenn der angewendete Ausdruck für ein beliebiges Mitglied der Sammlung wahr ist; andernfalls gibt er „Falsch“ zurück.- Der
any-Operator ohne Argument gibttruezurück, wenn die Sammlung nicht leer ist.
- Der
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 veranschaulicht, wie Sie alle Firmenentitätsdatensätze, die mindestens eine E-Mail mit „sometext“ im Betreff enthalten, abrufen können.
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 veranschaulicht, wie Sie alle Firmenentitätsdatensätze, bei denen alle zugeordneten Aufgaben geschlossen sind, abrufen können:
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 veranschaulicht, wie Sie alle Firmenentitätsdatensätze, die mindestens eine E-Mail mit „sometext“ im Betreff enthalten und deren statecode aktiv ist, abrufen können.
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 bis zu 500 Gesamtbedingungen in eine Abfrage einschließen. Andernfalls wird diese Fehlermeldung 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 Abfragefunktion In oder NotIn verwenden, die mit Zahlen, eindeutigen Bezeichnern und Zeichenfolgen mit bis zu 850 Zeichen verwendet werden können.
Nächste Schritte,
Erfahren Sie, wie Sie Ergebnisse auslagern.