Uso del parámetro de consulta $filter

Artículo
04/21/2024

Microsoft Graph admite el $filter parámetro de consulta OData para recuperar un subconjunto de una colección.

La expresión especificada con $filter se evalúa para cada recurso de la colección y solo los elementos en los que se evalúa true la expresión se incluyen en la respuesta. Los recursos para los que la expresión se evalúa false como o como , o que hacen referencia a nullpropiedades que no están disponibles debido a permisos, se omiten de la respuesta.

El $filter parámetro de consulta también se puede aplicar a relaciones como members, memberOf, transitiveMembers y transitiveMemberOf. Por ejemplo, "obtener todos los grupos de seguridad de los que soy miembro".

Operadores y funciones admitidos en expresiones de filtro

Microsoft Graph admite el uso de los siguientes operadores y funciones. Sin embargo, la compatibilidad con recursos individuales y sus propiedades o relaciones puede variar. Además, algunas propiedades y relaciones solo admiten $filterconsultas avanzadas. Consulte la documentación específica del recurso para obtener más información y Sintaxis para usar el parámetro de consulta OData de filtro para obtener ejemplos de cómo usar estos operadores y funciones.

Tipo de operador	Operador
Operadores de igualdad	Es igual (`eq`) No es igual (`ne`) Negación lógica (`not`) En (`in`) Tiene (`has`) Nota: Cuando se usa el `in` operador , la solicitud se limita a 15 expresiones en la cláusula de filtro de forma predeterminada o una longitud de dirección URL de 2048 caracteres cuando se usan funcionalidades de consulta avanzadas.
Operadores relacionales	Menor que (`lt`) Mayor que (`gt`) Menor o igual que (`le`) Mayor o igual que (`ge`)
Operador lambda	Cualquiera ( `any` ) Todo (`all`)
Operadores condicionales	Y (`and`) O (`or`)
Funciones	Empieza por ( `startswith` ) Termina con ( `endswith` ) Contiene (`contains`)

Filtrar mediante operadores lambda

OData define los any operadores y all para evaluar las coincidencias en propiedades con varios valores, es decir, una colección de valores primitivos, como tipos String o una colección de recursos.

Operador `any`

El any operador aplica iterativamente una expresión booleana a cada elemento de una colección y devuelve true si la expresión es true para al menos un elemento de la colección; de lo contrario, devuelve false. La siguiente cadena de consulta muestra la sintaxis del any operador :

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

Dónde

collection es la propiedad que contiene una colección de valores o una colección de propiedades complejas.
property:property es la variable de intervalo que contiene el elemento actual de la colección durante la iteración. Esta variable se puede denominar casi cualquier cosa, por ejemplo, p:p.
subProperty es necesario cuando la consulta se aplica a una colección de entidades. Representa la propiedad del tipo complejo con el que se va a buscar coincidencias.
value-to-match representa el miembro de la colección con la que se va a buscar coincidencias.

La sintaxis equivalente en C# y LINQ es la siguiente:

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

Por ejemplo, la propiedad imAddresses del user recurso contiene una colección de tipos primitivos String. La consulta siguiente recupera solo a los usuarios con al menos una 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://learn.microsoft.com/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')";
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "imAddresses/any(i:i eq 'admin@contoso.com')"



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



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

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

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


from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "imAddresses/any(i:i eq 'admin@contoso.com')",
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

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

La propiedad assignedLicenses del user recurso contiene una colección de objetos assignedLicense , un tipo complejo con dos propiedades, skuId y disabledPlans. La consulta siguiente recupera solo a los usuarios con al menos una licencia asignada identificada por el 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://learn.microsoft.com/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)";
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)"



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



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

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

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


from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)",
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

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

Para negar el resultado de la expresión dentro de la cláusula any use el operador not no el operador ne. Por ejemplo, la consulta siguiente recupera solo a los usuarios a los que no se les asigna el 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://learn.microsoft.com/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");
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))" --count "true" --consistency-level "eventual"



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
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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,
}

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


from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "NOT(imAddresses/any(i:i eq 'admin@contoso.com'))",
		count = True,
)

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


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

Operador `all`

El all operador aplica una expresión booleana a cada miembro de una colección y devuelve true si la expresión es true para todos los elementos de la colección; de lo contrario, devuelve false. Actualmente, no se admite en Microsoft Graph.

Ejemplos que usan el operador de consulta de filtro

En la tabla siguiente se muestran algunos ejemplos de uso del parámetro de consulta $filter. Para obtener más información, vea el protocolo OData.

Nota:

Los ejemplos marcados con ^** solo se admiten con funcionalidades de consulta avanzadas.
Haga clic en el método HTTP para probar los ejemplos en el Explorador de Graph.

Descripción	Ejemplo
Obtener todos los usuarios con el nombre Mary en varias propiedades.	GET`~/users?$filter=startswith(displayName,'mary') or startswith(givenName,'mary') or startswith(surname,'mary') or startswith(mail,'mary') or startswith(userPrincipalName,'mary')`
Obtener todos los usuarios con un dominio de correo igual a 'hotmail.com'	OBTENER`~/users?$count=true&$filter=endswith(mail,'@hotmail.com')`^**
Obtener todos los usuarios sin licencias asignadas	OBTENER`~/users?$filter=assignedLicenses/$count eq 0&$count=true`^**
Obtener todos los eventos del usuario que inició sesión que comiencen después del 1/7/2017.	A VER`~/me/events?$filter=start/dateTime ge '2017-07-01T08:00'`. NOTA: La propiedad dateTime de la entidad de evento es un tipo String.
Obtener todos los correos electrónicos de una dirección específica recibidos por el usuario que inició sesión.	GET`~/me/messages?$filter=from/emailAddress/address eq 'someuser@example.com'`
Obtener todos los correos electrónicos recibidos en abril de 2017 por el usuario que inició sesión.	GET`~/me/mailFolders/inbox/messages?$filter=ReceivedDateTime ge 2017-04-01 and receivedDateTime lt 2017-05-01`
Obtener todos los correos electrónicos no leídos en la Bandeja de entrada del usuario que inició sesión.	GET`~/me/mailFolders/inbox/messages?$filter=isRead eq false`
Obtener todos los usuarios de los departamentos de ventas y minoristas.	GET`~/users?$filter=department in ('Retail', 'Sales')`
Enumerar a los usuarios con un plan de servicio determinado que se encuentra en un estado suspendido.	OBTENER`~/users?$filter=assignedPlans/any(a:a/servicePlanId eq 2e2ddb96-6af9-4b1d-a3f0-d6ecfd22edb2 and a/capabilityStatus eq 'Suspended')&$count=true`^**
Enumerar todos los grupos que no sean de Microsoft 365 de una organización.	OBTENER`~/groups?$filter=NOT groupTypes/any(c:c eq 'Unified')&$count=true`^**
Enumere todos los usuarios cuyo nombre de empresa no sea indefinido (es decir, no un `null` valor) o Microsoft.	OBTENER`~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true`^**
Enumere todos los usuarios cuyo nombre de empresa sea indefinido o Microsoft.	OBTENER`~/users?$filter=companyName in (null, 'Microsoft')&$count=true`^**
Emplee la transmisión de OData para obtener la pertenencia transitiva en grupos con un nombre para mostrar que comience por "a", incluido un recuento de objetos devueltos.	OBTENER`~/me/transitiveMemberOf/microsoft.graph.group?$count=true&$filter=startswith(displayName, 'a')`^**

Sintaxis para usar el parámetro de consulta OData de filtro

En el artículo siguiente se muestra la sintaxis para usar el $filter parámetro de consulta OData y sus operadores asociados. Los ejemplos se proporcionan solo para orientación y no reflejan una lista completa para la aplicación de $filter.

Nota:

Los valores GUID y DateTimeOffset no se incluyen entre comillas en $filter expresiones.

^** : este ejemplo solo se admite con funcionalidades de consulta avanzadas.

Para tipos primitivos únicos como String, Int y dates

Operador	Sintaxis
`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')` Nota: En el caso de las cadenas de consulta que usan `in` el operador , la solicitud se limita a 15 expresiones en la cláusula de filtro de forma predeterminada o una longitud de dirección URL de 2.048 caracteres cuando se usan funcionalidades avanzadas de consulta.
`le`	`~/devices?$filter=registrationDateTime le 2021-01-02T12:00:00Z`^**
`ge`	`~/devices?$filter=registrationDateTime ge 2021-01-02T12:00:00Z`^**
`not` y `endswith`	`~/users?$filter=not(endswith(mail, 'contoso.com'))`^**
`not` y `startswith`	`~/users?$filter=not(startswith(mail, 'A'))`^**
`not` y `eq`	`~/users?$filter=not(companyName eq 'Contoso E.A.')`^**
`not` y `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'`

Para una colección de tipos primitivos

Operador (s)	Sintaxis
`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` y `endswith`	`~/groups?$filter=not(endswith(mail,'contoso.com'))`^**
`not` y `startswith`	`~/groups?$filter=not(startswith(mail,'Pineview'))`^**
`not` y `eq`	`~/groups?$filter=not(mail eq 'PineviewSchoolStaff@Contoso.com')`^**
`eq` y `$count` para colecciones vacías	`~/users?$filter=assignedLicenses/$count eq 0`^**
`ne` y `$count` para colecciones vacías	`~/users?$filter=assignedLicenses/$count ne 0`^**
`not` y `$count` para colecciones vacías	`~/users?$filter=not(assignedLicenses/$count eq 0)`^**
`$count` para colecciones con un objeto	`~/servicePrincipals?$filter=owners/$count eq 1`^**

Para tipos DE GUID

Operador (s)	Sintaxis
`eq`	`~/servicePrincipals?$filter=appOwnerOrganizationId eq 72f988bf-86f1-41af-91ab-2d7cd011db47`^**
`not`	`~/servicePrincipals?$filter=not(appOwnerOrganizationId eq 72f988bf-86f1-41af-91ab-2d7cd011db47)`^**

Para una colección de tipos GUID

Operador (s)	Sintaxis
`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)`^**

Para una colección de tipos complejos

Operador (s)	Sintaxis
`eq`	`~/users?$filter=certificateUserIds/any(x:x eq '9876543210@mil')`^**
`not` y `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'))`^**

Funcionalidades avanzadas de consulta en objetos de directorio

Uso del parámetro de consulta $filter

Operadores y funciones admitidos en expresiones de filtro

Filtrar mediante operadores lambda

Operador `any`

Operador `all`

Ejemplos que usan el operador de consulta de filtro

Sintaxis para usar el parámetro de consulta OData de filtro

Para tipos primitivos únicos como String, Int y dates

Para una colección de tipos primitivos

Para tipos DE GUID

Para una colección de tipos GUID

Para una colección de tipos complejos

Comentarios

Comentarios

Recursos adicionales

Uso del parámetro de consulta $filter

Operadores y funciones admitidos en expresiones de filtro

Filtrar mediante operadores lambda

Operador any

Operador all

Ejemplos que usan el operador de consulta de filtro

Sintaxis para usar el parámetro de consulta OData de filtro

Para tipos primitivos únicos como String, Int y dates

Para una colección de tipos primitivos

Para tipos DE GUID

Para una colección de tipos GUID

Para una colección de tipos complejos

Contenido relacionado

Comentarios

Comentarios

Recursos adicionales

Operador `any`

Operador `all`