Partager via


Utiliser le paramètre de requête $filter

Microsoft Graph prend en charge le $filter paramètre de requête OData pour récupérer un sous-ensemble d’une collection.

L’expression spécifiée avec $filter est évaluée pour chaque ressource de la collection, et seuls les éléments dont l’expression prend la valeur true sont inclus dans la réponse. Les ressources pour lesquelles l’expression prend la valeur ou nullla valeur , ou les propriétés de référence qui ne sont pas disponibles en raison d’autorisations, sont omises false de la réponse.

Le $filter paramètre de requête peut également être appliqué à des relations telles que members, memberOf, transitiveMembers et transitiveMemberOf. Par exemple, « obtenir tous les groupes de sécurité dont je suis membre ».

Opérateurs et fonctions pris en charge dans les expressions de filtre

Microsoft Graph prend en charge l’utilisation des opérateurs et fonctions suivants. Toutefois, la prise en charge par des ressources individuelles et leurs propriétés ou relations peuvent varier. En outre, certaines propriétés et relations prennent en charge $filter uniquement les requêtes avancées. Pour plus d’informations sur l’utilisation du paramètre de requête OData de filtre, consultez la documentation sur les ressources spécifiques et la syntaxe pour utiliser le paramètre de requête OData de filtre pour obtenir des exemples d’utilisation de ces opérateurs et fonctions.

Type d'opérateur Opérateur
Opérateurs d’égalité
  • Égal à (eq)
  • N’est pas égal à (ne)
  • Négation logique ( not )
  • En (in)
  • A (has)


Note: Lorsque vous utilisez l’opérateur in , la requête est limitée à 15 expressions dans la clause de filtre par défaut ou à une longueur d’URL de 2 048 caractères lors de l’utilisation de fonctionnalités de requête avancées.
Opérateurs relationnels
  • Inférieur à (lt)
  • Supérieur à (gt)
  • Inférieur ou égal à (le)
  • Supérieur ou égal à (ge)
Opérateurs lambda
  • Tout ( any )
  • Tous (all)
Opérateurs conditionnels
  • Et (and)
  • Ou (or)
Fonctions
  • Commence par ( startswith )
  • Se termine par ( endswith )
  • Contient (contains)

Filtrage en utilisant des opérateurs lambda

OData définit les any opérateurs et all pour évaluer les correspondances sur les propriétés à valeurs multiples, c’est-à-dire la collection de valeurs primitives telles que les types String ou la collection de ressources.

Opérateur any

L’opérateur any applique de façon itérative une expression booléenne à chaque élément d’une collection et retourne true si l’expression concerne trueau moins un élément de la collection ; sinon, il retourne false. La chaîne de requête suivante montre la syntaxe de l’opérateur any :

$filter=collection/any(property:property/subProperty eq 'value-to-match')

  • collection est la propriété qui contient une collection de valeurs ou une collection de propriétés complexes.
  • property :property est la variable de plage qui contient l’élément actuel de la collection pendant l’itération. Cette variable peut être nommée presque n’importe quoi, par exemple p :p.
  • subProperty est requis lorsque la requête s’applique à une collection d’entités. Il représente la propriété du type complexe auquel vous faites correspondre la valeur.
  • value-to-match représente le membre de la collection avec laquelle vous effectuez une correspondance.

La syntaxe équivalente dans C# et LINQ est la suivante :

collection.Any(property => property.subProperty == "value-to-match")

Par exemple, la propriété imAddresses de la user ressource contient une collection de types primitifs String. La requête suivante récupère uniquement les utilisateurs avec au moins une adresse imAddress de admin@contoso.com.

GET https://graph.microsoft.com/v1.0/users?$filter=imAddresses/any(i:i eq 'admin@contoso.com')

La propriété assignedLicenses de la user ressource contient une collection d’objets assignedLicense , un type complexe avec deux propriétés, skuId et disabledPlans. La requête suivante récupère uniquement les utilisateurs avec au moins une licence affectée identifiée par le skuId184efa21-98c3-4e5d-95ab-d07053a96e67.

GET https://graph.microsoft.com/v1.0/users?$filter=assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)

Pour inverser le résultat de l’expression dans la clause any, utilisez l’opérateur not, et non pas l’opérateur ne. Par exemple, la requête suivante récupère uniquement les utilisateurs qui ne sont pas affectés à l’adresse imAddress de admin@contoso.com.

Remarque : Pour les objets d’annuaire tels que les utilisateurs, les opérateurs not et ne sont pris en charge uniquement dans requêtes avancées.

GET https://graph.microsoft.com/v1.0/users?$filter=NOT(imAddresses/any(i:i eq 'admin@contoso.com'))&$count=true
ConsistencyLevel: eventual

Opérateur all

L’opérateur all applique une expression booléenne à chaque membre d’une collection et retourne true si l’expression concerne truetous les éléments de la collection ; sinon, il retourne false. Actuellement, il n’est pas pris en charge dans Microsoft Graph.

Exemples utilisant l’opérateur de requête filtre

Le tableau suivant répertorie quelques exemples où le paramètre de requête $filter est utilisé. Pour plus d’informations, consultez le protocole OData.

Remarque

Description Exemple
Trouver toutes les utilisatrices qui s’appellent Mary dans plusieurs propriétés. GET~/users?$filter=startswith(displayName,'mary') or startswith(givenName,'mary') or startswith(surname,'mary') or startswith(mail,'mary') or startswith(userPrincipalName,'mary')
Trouver tous les utilisateurs du domaine d’e-mail « hotmail.com » AVOIR~/users?$count=true&$filter=endswith(mail,'@hotmail.com') **
Obtenir tous les utilisateurs sans licences attribuées AVOIR~/users?$filter=assignedLicenses/$count eq 0&$count=true **
Obtenir tous les événements de l’utilisateur connecté qui commencent après le 01/07/2017. GET~/me/events?$filter=start/dateTime ge '2017-07-01T08:00'.
NOTE: La propriété dateTime de l’entité d’événement est de type String.
Obtenir tous les messages électroniques provenant d’une adresse spécifique reçus par l’utilisateur connecté. GET~/me/messages?$filter=from/emailAddress/address eq 'someuser@example.com'
Obtenir tous les messages électroniques reçus par l’utilisateur connecté en avril 2017. GET~/me/mailFolders/inbox/messages?$filter=ReceivedDateTime ge 2017-04-01 and receivedDateTime lt 2017-05-01
Obtenir tous les messages non lus dans la boîte de réception de l’utilisateur connecté. GET~/me/mailFolders/inbox/messages?$filter=isRead eq false
Obtenir tous les utilisateurs dans les services Vente au détail et Ventes. GET~/users?$filter=department in ('Retail', 'Sales')
Répertorie les utilisateurs avec un plan de services particulier qui est dans un état suspendu. AVOIR~/users?$filter=assignedPlans/any(a:a/servicePlanId eq 2e2ddb96-6af9-4b1d-a3f0-d6ecfd22edb2 and a/capabilityStatus eq 'Suspended')&$count=true **
Répertorier tous les groupes non Microsoft 365 dans une organisation. AVOIR~/groups?$filter=NOT groupTypes/any(c:c eq 'Unified')&$count=true **
Répertorier tous les utilisateurs dont le nom de l’entreprise n’est pas défini (autrement dit, pas une null valeur) ou Microsoft. AVOIR~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true **
Répertorier tous les utilisateurs dont le nom de l’entreprise est indéfini ou Microsoft. AVOIR~/users?$filter=companyName in (null, 'Microsoft')&$count=true **
Utilisez la conversion OData pour obtenir un abonnement transitif dans les groupes avec un nom complet commençant par « a », y compris le nombre d’objets retournés. AVOIR~/me/transitiveMemberOf/microsoft.graph.group?$count=true&$filter=startswith(displayName, 'a') **

Syntaxe pour l’utilisation du paramètre de requête OData de filtre

L’article suivant illustre la syntaxe de l’utilisation du $filter paramètre de requête OData et de ses opérateurs associés. Les exemples sont fournis à titre indicatif uniquement et ne reflètent pas une liste complète pour l’application de $filter.

Remarque

  • Les valeurs GUID et DateTimeOffset ne sont pas placées entre guillemets dans les $filter expressions.

** : cet exemple est pris en charge uniquement avec des fonctionnalités de requête avancées.

Pour les types primitifs uniques tels que String, Int et dates

Opérateur Syntaxe
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')

Note: Pour les chaînes de requête utilisant in l’opérateur, la requête est limitée à 15 expressions dans la clause de filtre par défaut ou à une longueur d’URL de 2 048 caractères lors de l’utilisation de fonctionnalités de requête avancées.
le ~/devices?$filter=registrationDateTime le 2021-01-02T12:00:00Z **
ge ~/devices?$filter=registrationDateTime ge 2021-01-02T12:00:00Z **
not et endswith ~/users?$filter=not(endswith(mail, 'contoso.com')) **
not et startswith ~/users?$filter=not(startswith(mail, 'A')) **
not et eq ~/users?$filter=not(companyName eq 'Contoso E.A.') **
not et 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'

Pour une collection de types primitifs

Opérateur(s) Syntaxe
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 et endswith ~/groups?$filter=not(endswith(mail,'contoso.com')) **
not et startswith ~/groups?$filter=not(startswith(mail,'Pineview')) **
not et eq ~/groups?$filter=not(mail eq 'PineviewSchoolStaff@Contoso.com') **
eq et $count pour les collections vides ~/users?$filter=assignedLicenses/$count eq 0 **
ne et $count pour les collections vides ~/users?$filter=assignedLicenses/$count ne 0 **
not et $count pour les collections vides ~/users?$filter=not(assignedLicenses/$count eq 0) **
$count pour les collections avec un seul objet ~/servicePrincipals?$filter=owners/$count eq 1 **

Pour les types GUID

Opérateur(s) Syntaxe
eq ~/servicePrincipals?$filter=appOwnerOrganizationId eq 72f988bf-86f1-41af-91ab-2d7cd011db47 **
not ~/servicePrincipals?$filter=not(appOwnerOrganizationId eq 72f988bf-86f1-41af-91ab-2d7cd011db47) **

Pour une collection de types GUID

Opérateur(s) Syntaxe
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) **

Pour une collection de types complexes

Opérateur(s) Syntaxe
eq ~/users?$filter=certificateUserIds/any(x:x eq '9876543210@mil') **
not et 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')) **