Utiliser le paramètre de requête $filter

Article
07/04/2024

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

Où

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://zcusa.951200.xyz/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "imAddresses/any(i:i eq 'admin@contoso.com')";
});



mgc users list --filter "imAddresses/any(i:i eq 'admin@contoso.com')"



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)


requestFilter := "imAddresses/any(i:i eq 'admin@contoso.com')"

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://zcusa.951200.xyz/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "imAddresses/any(i:i eq 'admin@contoso.com')";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('imAddresses/any(i:i eq \'admin@contoso.com\')')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "imAddresses/any(i:i eq 'admin@contoso.com')";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "imAddresses/any(i:i eq 'admin@contoso.com')"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://zcusa.951200.xyz/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "imAddresses/any(i:i eq 'admin@contoso.com')",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

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)


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://zcusa.951200.xyz/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)";
});



mgc users list --filter "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)"



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)


requestFilter := "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)"

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://zcusa.951200.xyz/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://zcusa.951200.xyz/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

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.

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://zcusa.951200.xyz/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))";
	requestConfiguration.QueryParameters.Count = true;
	requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});



mgc users list --filter "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))" --count "true" --consistency-level "eventual"



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")


requestFilter := "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))"
requestCount := true

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
	Count: &requestCount,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://zcusa.951200.xyz/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))";
	requestConfiguration.queryParameters.count = true;
	requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.header('ConsistencyLevel','eventual')
	.filter('NOT(imAddresses/any(i:i eq \'admin@contoso.com\'))')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$headers = [
		'ConsistencyLevel' => 'eventual',
	];
$requestConfiguration->headers = $headers;

$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))";
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))" -CountVariable CountVar  -ConsistencyLevel eventual


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://zcusa.951200.xyz/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))",
		count = True,
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")


result = await graph_client.users.get(request_configuration = request_configuration)

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

Les exemples marqués avec ^** sont uniquement pris en charge avec des fonctionnalités de requête avancées.
Cliquez sur la méthode HTTP pour essayer les exemples dans l’Explorateur Graph.

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'))`^**

Fonctionnalités de requête avancées sur les objets d’annuaire

Partager via

Utiliser le paramètre de requête $filter

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

Filtrage en utilisant des opérateurs lambda

Opérateur `any`

Opérateur `all`

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

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

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

Pour une collection de types primitifs

Pour les types GUID

Pour une collection de types GUID

Pour une collection de types complexes

Commentaires

Ressources supplémentaires

Partager via

Utiliser le paramètre de requête $filter

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

Filtrage en utilisant des opérateurs lambda

Opérateur any

Opérateur all

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

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

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

Pour une collection de types primitifs

Pour les types GUID

Pour une collection de types GUID

Pour une collection de types complexes

Contenu connexe

Commentaires

Ressources supplémentaires

Opérateur `any`

Opérateur `all`