Verwenden des abfrageparameters $filter

Microsoft Graph unterstützt den $filterOData-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 nullwird 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
  • Gleich (eq)
  • Ungleich (ne)
  • Logische Negation (not)
  • In (in)
  • Hat (has)


Hinweis: 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
  • Kleiner als (lt)
  • Größer als (gt)
  • Kleiner oder gleich (le)
  • Größer oder gleich (ge)
Lambda-Operatoren
  • Beliebig (any)
  • Alle (all)
Bedingte Operatoren
  • Und (and)
  • Oder (or)
Funktionen
  • Beginnt mit (startswith)
  • Endet mit (endswith)
  • Enthält (contains)

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.comzugewiesen ist.

Hinweis: Für Verzeichnisobjekte wie Benutzer werden die Operatoren not und ne 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

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'
HINWEIS: 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')

Hinweis: 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')) **