Verwenden des abfrageparameters $filter
Microsoft Graph unterstützt den $filter
OData-Abfrageparameter , um eine Teilmenge einer Sammlung abzurufen.
Der mit $filter
angegebene Ausdruck wird für jede Ressource in der Auflistung ausgewertet, und nur Elemente, für die der Ausdruck ausgewertet true
wird, werden in die Antwort eingeschlossen. Ressourcen, für die der Ausdruck als false
oder ausgewertet null
wird oder die auf Eigenschaften verweisen, die aufgrund von Berechtigungen nicht verfügbar sind, werden in der Antwort weggelassen.
Der $filter
Abfrageparameter kann auch auf Beziehungen wie members, memberOf, transitiveMembers und transitiveMemberOf angewendet werden. Beispiel: "Abrufen aller Sicherheitsgruppen, in denen ich Mitglied bin".
In Filterausdrücken unterstützte Operatoren und Funktionen
Microsoft Graph unterstützt die Verwendung der folgenden Operatoren und Funktionen. Die Unterstützung durch einzelne Ressourcen und deren Eigenschaften oder Beziehungen kann jedoch variieren. Darüber hinaus unterstützen $filter
einige Eigenschaften und Beziehungen nur bei erweiterten Abfragen. Ausführliche Informationen finden Sie in der Dokumentation zu den ressourcenspezifischen Ressourcen und syntax für die Verwendung des OData-Abfrageparameters filter für Beispiele zur Verwendung dieser Operatoren und Funktionen.
Operatortyp | Operator |
---|---|
Gleichheitsoperatoren |
Anmerkung: Bei Verwendung des in Operators ist die Anforderung standardmäßig auf 15 Ausdrücke in der Filterklausel oder eine URL-Länge von 2.048 Zeichen beschränkt, wenn erweiterte Abfragefunktionen verwendet werden. |
Relationaler Operator |
|
Lambda-Operatoren |
|
Bedingte Operatoren |
|
Funktionen |
|
Filtern mit Lambdaoperatoren
OData definiert die any
Operatoren und all
zum Auswerten von Übereinstimmungen für mehrwertige Eigenschaften, d. h. entweder eine Auflistung von primitiven Werten wie Zeichenfolgentypen oder eine Sammlung von Ressourcen.
any
-Operator
Der any
Operator wendet iterativ einen booleschen Ausdruck auf jedes Element einer Auflistung an und gibt zurücktrue
, wenn der Ausdruck für mindestens ein Element der Auflistung isttrue
, andernfalls wird zurückgegebenfalse
. Die folgende Abfragezeichenfolge zeigt die Syntax für den any
Operator:
$filter=collection/any(property:property/subProperty eq 'value-to-match')
Dabei gilt:
- collection ist die Eigenschaft, die eine Auflistung von Werten oder eine Auflistung komplexer Eigenschaften enthält.
- property:property ist die Bereichsvariable, die das aktuelle Element der Auflistung während der Iteration enthält. Diese Variable kann fast alles genannt werden, z. B. p:p.
- subProperty ist erforderlich, wenn die Abfrage auf eine Auflistung von Entitäten angewendet wird. Es stellt die -Eigenschaft des komplexen Typs dar, dessen Wert Sie abgleichen.
- value-to-match stellt das Element der Sammlung dar, mit der Sie übereinstimmen.
Die entsprechende Syntax in C#
und LINQ
lautet wie folgt:
collection.Any(property => property.subProperty == "value-to-match")
Beispielsweise enthält die imAddresses-Eigenschaft der user
Ressource eine Auflistung von primitiven String-Typen. Die folgende Abfrage ruft nur Benutzer mit mindestens einer imAddress von ab admin@contoso.com
.
GET https://graph.microsoft.com/v1.0/users?$filter=imAddresses/any(i:i eq 'admin@contoso.com')
Die assignedLicenses-Eigenschaft der user
Ressource enthält eine Auflistung von assignedLicense-Objekten , einen komplexen Typ mit zwei Eigenschaften, skuId und disabledPlans. Die folgende Abfrage ruft nur Benutzer mit mindestens einer zugewiesenen Lizenz ab, die durch die skuId184efa21-98c3-4e5d-95ab-d07053a96e67
identifiziert wird.
GET https://graph.microsoft.com/v1.0/users?$filter=assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)
Um das Ergebnis des Ausdrucks innerhalb der any
-Klausel zu negieren, verwenden Sie den Operator not
, nicht den Operator ne
. Die folgende Abfrage ruft beispielsweise nur Benutzer ab, denen nicht die imAddress von admin@contoso.com
zugewiesen ist.
Hinweis: Für Verzeichnisobjekte wie Benutzer werden die Operatoren
not
undne
nur in erweiterten Abfragen unterstützt.
GET https://graph.microsoft.com/v1.0/users?$filter=NOT(imAddresses/any(i:i eq 'admin@contoso.com'))&$count=true
ConsistencyLevel: eventual
all
-Operator
Der all
Operator wendet einen booleschen Ausdruck auf jedes Element einer Auflistung an und gibt zurücktrue
, wenn der Ausdruck für alle Elemente der Auflistung isttrue
, andernfalls wird zurückgegebenfalse
. Derzeit wird dies in Microsoft Graph nicht unterstützt.
Beispiele für die Verwendung des Filterabfrageoperators
Die folgende Tabelle enthält einige Beispiele, welche die $filter
-Abfrageparameter verwenden. Weitere Informationen finden Sie unter OData-Protokoll.
Hinweis
- Beispiele, die mit ** gekennzeichnet sind, werden nur mit erweiterten Abfragefunktionen unterstützt.
- Klicken Sie auf die HTTP-Methode, um die Beispiele im Graph-Explorer auszuprobieren.
Beschreibung | Beispiel |
---|---|
In mehreren Eigenschaften alle Benutzer mit dem Namen „Mary“ abrufen. |
ABRUFEN~/users?$filter=startswith(displayName,'mary') or startswith(givenName,'mary') or startswith(surname,'mary') or startswith(mail,'mary') or startswith(userPrincipalName,'mary') |
Alle Benutzer mit der E-Mail-Domäne gleich „hotmail.com“ abrufen. |
ERHALTEN~/users?$count=true&$filter=endswith(mail,'@hotmail.com') ** |
Alle Benutzer ohne zugewiesene Lizenzen anzeigen |
ERHALTEN~/users?$filter=assignedLicenses/$count eq 0&$count=true ** |
Alle Ereignisse des angemeldeten Benutzers abrufen, die nach dem 01.07.2017 beginnen. |
GET.~/me/events?$filter=start/dateTime ge '2017-07-01T08:00' ANMERKUNG: Die dateTime-Eigenschaft der Ereignisentität ist ein String-Typ. |
Alle E-Mails von einer bestimmten Adresse abrufen, die der angemeldete Benutzer erhalten hat. |
ABRUFEN~/me/messages?$filter=from/emailAddress/address eq 'someuser@example.com' |
Alle E-Mails abrufen, die der angemeldete Benutzer im April 2017 erhalten hat. |
ABRUFEN~/me/mailFolders/inbox/messages?$filter=ReceivedDateTime ge 2017-04-01 and receivedDateTime lt 2017-05-01 |
Alle ungelesenen E-Mails im Postfach des angemeldeten Benutzers abrufen. |
ABRUFEN~/me/mailFolders/inbox/messages?$filter=isRead eq false |
Alle Benutzer in den Abteilungen „Einzelhandel“ und „Vertrieb“ abrufen. |
ABRUFEN~/users?$filter=department in ('Retail', 'Sales') |
Benutzer mit einem bestimmten Serviceplan auflisten, der sich in einem angehaltenen Zustand befindet. |
ERHALTEN~/users?$filter=assignedPlans/any(a:a/servicePlanId eq 2e2ddb96-6af9-4b1d-a3f0-d6ecfd22edb2 and a/capabilityStatus eq 'Suspended')&$count=true ** |
Alle Microsoft 365-Gruppen in einer Organisation auflisten. |
ERHALTEN~/groups?$filter=NOT groupTypes/any(c:c eq 'Unified')&$count=true ** |
Listet alle Benutzer auf, deren Firmenname nicht undefiniert ist (d. h. kein null Wert) oder Microsoft. |
ERHALTEN~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true ** |
Alle Benutzer auflisten, deren Unternehmensname entweder undefiniert oder Microsoft ist. |
ERHALTEN~/users?$filter=companyName in (null, 'Microsoft')&$count=true ** |
Verwenden Sie die CAST-Funktion von OData, um transitive Mitgliedschaften in Gruppen mit einem Anzeigenamen zu erhalten, der mit „A“ beginnt, einschließlich der Anzahl der zurückgegebenen Objekte. |
ERHALTEN~/me/transitiveMemberOf/microsoft.graph.group?$count=true&$filter=startswith(displayName, 'a') ** |
Syntax für die Verwendung des Filter-OData-Abfrageparameters
Im folgenden Artikel wird die Syntax für die Verwendung des $filter
OData-Abfrageparameters und der zugehörigen Operatoren veranschaulicht. Die Beispiele dienen nur als Anleitung und enthalten keine umfassende Liste für die Anwendung von $filter
.
Hinweis
- GUID- und DateTimeOffset-Werte sind in Ausdrücken nicht in
$filter
Anführungszeichen eingeschlossen.
** : Dieses Beispiel wird nur mit erweiterten Abfragefunktionen unterstützt.
Für einzelne primitive Typen wie String, Int und Dates
Operator | Syntax |
---|---|
eq |
~/users?$filter=userType eq 'Member' |
not |
~/users?$filter=not(userType eq 'Member') ** |
ne |
~/users?$filter=companyName ne null ** |
startswith |
~/users?$filter=startswith(userPrincipalName, 'admin') |
endswith |
~/users?$filter=endswith(mail,'@outlook.com') ** |
in |
~/users?$filter=mail in ('mail1@domain.com', 'mail2@domain.com') Anmerkung: Bei Abfragezeichenfolgen, die den Operator verwenden in , ist die Anforderung standardmäßig auf 15 Ausdrücke in der Filterklausel oder eine URL-Länge von 2.048 Zeichen beschränkt, wenn erweiterte Abfragefunktionen verwendet werden. |
le |
~/devices?$filter=registrationDateTime le 2021-01-02T12:00:00Z ** |
ge |
~/devices?$filter=registrationDateTime ge 2021-01-02T12:00:00Z ** |
not und endswith |
~/users?$filter=not(endswith(mail, 'contoso.com')) ** |
not und startswith |
~/users?$filter=not(startswith(mail, 'A')) ** |
not und eq |
~/users?$filter=not(companyName eq 'Contoso E.A.') ** |
not und in |
~/users?$filter=not(userType in ('Member')) ** |
contains |
~/identityGovernance/accessReviews/definitions?$filter=contains(scope/microsoft.graph.accessReviewQueryScope/query, './members') |
has |
~/identity/conditionalAccess/templates?$filter=scenarios has 'secureFoundation' |
Für eine Auflistung primitiver Typen
Operator (s) | Syntax |
---|---|
eq |
~/groups?$filter=groupTypes/any(c:c eq 'Unified') |
not |
~/groups?$filter=not(groupTypes/any(c:c eq 'Unified')) ** |
ne |
~/users?$filter=companyName ne null ** |
startswith |
~/users?$filter=businessPhones/any(p:startswith(p, '44')) ** |
endswith |
~/users?$filter=endswith(mail,'@outlook.com') ** |
not und endswith |
~/groups?$filter=not(endswith(mail,'contoso.com')) ** |
not und startswith |
~/groups?$filter=not(startswith(mail,'Pineview')) ** |
not und eq |
~/groups?$filter=not(mail eq 'PineviewSchoolStaff@Contoso.com') ** |
eq und $count für leere Sammlungen |
~/users?$filter=assignedLicenses/$count eq 0 ** |
ne und $count für leere Sammlungen |
~/users?$filter=assignedLicenses/$count ne 0 ** |
not und $count für leere Sammlungen |
~/users?$filter=not(assignedLicenses/$count eq 0) ** |
$count für Auflistungen mit einem Objekt |
~/servicePrincipals?$filter=owners/$count eq 1 ** |
Für GUID-Typen
Operator (s) | Syntax |
---|---|
eq |
~/servicePrincipals?$filter=appOwnerOrganizationId eq 72f988bf-86f1-41af-91ab-2d7cd011db47 ** |
not |
~/servicePrincipals?$filter=not(appOwnerOrganizationId eq 72f988bf-86f1-41af-91ab-2d7cd011db47) ** |
Für eine Auflistung von GUID-Typen
Operator (s) | Syntax |
---|---|
eq |
~/devices?$filter=alternativeSecurityIds/any(a:a/type eq 2) ** |
le |
~/devices?$filter=alternativeSecurityIds/any(a:a/type le 2) ** |
ge |
~/devices?$filter=alternativeSecurityIds/any(a:a/type ge 2) ** |
Für eine Auflistung komplexer Typen
Operator (s) | Syntax |
---|---|
eq |
~/users?$filter=certificateUserIds/any(x:x eq '9876543210@mil') ** |
not und eq |
~/users?$filter=not(certificateUserIds/any(x:x eq '9876543210@mil')) ** |
startswith |
~/users?$filter=certificateUserIds/any(x:startswith(x,'987654321')) ** |
endswith |
~/users?$filter=proxyAddresses/any(p:endswith(p,'contoso.com')) ** |