Usar o parâmetro de consulta $filter

O Microsoft Graph dá suporte ao $filter parâmetro de consulta OData para recuperar um subconjunto de uma coleção.

A expressão especificada com $filter é avaliada para cada recurso na coleção, e somente os itens em que a expressão é avaliada true são incluídos na resposta. Recursos para os quais a expressão é avaliada como ou false para null, ou cujas propriedades de referência que não estão disponíveis devido a permissões são omitidas da resposta.

O $filter parâmetro de consulta também pode ser aplicado a relações como members, memberOf, transitiveMembers e transitiveMemberOf. Por exemplo, "obter todos os grupos de segurança dos quais sou membro".

Operadores e funções com suporte em expressões de filtro

O Microsoft Graph dá suporte ao uso dos operadores e funções a seguir. No entanto, o suporte por recursos individuais e suas propriedades ou relacionamentos varia. Além disso, algumas propriedades e relações são compatíveis $filter apenas com consultas avançadas. Consulte a documentação de recursos específicos para obter detalhes e Sintaxe para usar o parâmetro de consulta OData de filtro para obter exemplos de como usar esses operadores e funções. Além disso, algumas limitações se aplicam.

Tipo de operador	Operador
Operadores de igualdade	Igual a (`eq`) Não é igual a (`ne`) Negação lógica (`not`) Em (`in`) Tem (`has`) Observação: Consulte Limitações de parâmetros de consulta nos problemas conhecidos para obter limitações para `in` e `eq` operadores.
Operadores relacionais	Menor que (`lt`) Maior que (`gt`) Menor ou igual a ( `le` ) Maior ou igual a (`ge`)
Operadores Lambda	Qualquer (`any`) Todos (`all`)
Operadores condicionais	E (`and`) Ou (`or`)
Functions	Inicia com ( `startswith` ) Termina com (`endswith`) Contém ( `contains` )

Filtrar usando operadores lambda

O OData define os any operadores and all para avaliar correspondências em propriedades de vários valores, ou seja, uma coleção de valores primitivos, como tipos String, ou uma coleção de recursos.

Operador `any`

O any operador aplica iterativamente uma expressão booleana a cada item de uma coleção e retorna true se a expressão for true para pelo menos um item da coleção, caso contrário, ele retorna false. A cadeia de caracteres de consulta a seguir mostra a sintaxe do any operador:

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

Em que

Coleção é a propriedade que contém uma coleção de valores ou uma coleção de propriedades complexas.
property:property é a variável de intervalo que contém o elemento atual da coleção durante a iteração. Essa variável pode ser nomeada como quase qualquer coisa, por exemplo, p:p.
subProperty é necessário quando a consulta se aplica a um conjunto de entidades. Ele representa a propriedade do tipo complexo cujo valor você está correspondendo.
value-to-match representa o membro da coleção com a qual você está correspondendo.

A sintaxe equivalente em C# e LINQ é a seguinte:

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

Por exemplo, a propriedade imAddresses do user recurso contém uma coleção de tipos primitivos String. A consulta a seguir recupera apenas usuários com pelo menos um 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')";
});



// 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://learn.microsoft.com/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://learn.microsoft.com/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)

A propriedade assignedLicenses do user recurso contém uma coleção de objetos assignedLicense , um tipo complexo com duas propriedades, skuId e disabledPlans. A consulta a seguir recupera apenas usuários com pelo menos uma licença atribuída identificada pelo 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)";
});



// 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://learn.microsoft.com/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://learn.microsoft.com/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)

Para negar o resultado da expressão dentro da cláusula any, use o operador not, não o operador ne. Por exemplo, a consulta a seguir recupera apenas usuários que não receberam o 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");
});



// 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://learn.microsoft.com/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://learn.microsoft.com/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)

Operador `all`

O all operador aplica uma expressão booleana a cada membro de uma coleção e retorna true se a expressão é true para todos os itens da coleção, caso contrário, retorna false. No momento, não há suporte para ele no Microsoft Graph.

Exemplos usando o operador de consulta de filtro

A tabela a seguir mostra alguns exemplos que usam o parâmetro de consulta $filter. Para obter mais informações, consulte o protocolo OData.

Observação

Os exemplos marcados com ^** só são suportados com recursos avançados de consulta.
Clique no método HTTP para experimentar os exemplos no Graph Explorer.

Descrição	Exemplo
Pesquisar por usuários com o nome Clara entre várias propriedades.	OBTER`~/users?$filter=startswith(displayName,'mary') or startswith(givenName,'mary') or startswith(surname,'mary') or startswith(mail,'mary') or startswith(userPrincipalName,'mary')`
Obter todos os usuários com o domínio de email igual a 'hotmail.com'	OBTER`~/users?$count=true&$filter=endswith(mail,'@hotmail.com')`^**
Obtenha todos os usuários sem licenças atribuídas	OBTER`~/users?$filter=assignedLicenses/$count eq 0&$count=true`^**
Obter todos os eventos do usuário conectado que começaram após 01/07/2017.	GET`~/me/events?$filter=start/dateTime ge '2017-07-01T08:00'`. OBSERVAÇÃO: A propriedade dateTime da entidade de evento é um tipo String.
Obter todos os emails de um endereço específico recebidos pelo usuário conectado.	OBTER`~/me/messages?$filter=from/emailAddress/address eq 'someuser@example.com'`
Obter todos os emails recebidos pelo usuário conectado em abril de 2017.	OBTER`~/me/mailFolders/inbox/messages?$filter=ReceivedDateTime ge 2017-04-01 and receivedDateTime lt 2017-05-01`
Obter todos os emails não lidos na caixa de entrada do usuário conectado.	OBTER`~/me/mailFolders/inbox/messages?$filter=isRead eq false`
Obter todos os usuários nos departamentos de Varejo e Vendas.	OBTER`~/users?$filter=department in ('Retail', 'Sales')`
Listar os usuários com um plano de serviço específico que está em um estado suspenso.	OBTER`~/users?$filter=assignedPlans/any(a:a/servicePlanId eq 2e2ddb96-6af9-4b1d-a3f0-d6ecfd22edb2 and a/capabilityStatus eq 'Suspended')&$count=true`^**
Listar todos os grupos que não são do Microsoft 365 em uma organização.	OBTER`~/groups?$filter=NOT groupTypes/any(c:c eq 'Unified')&$count=true`^**
Liste todos os usuários cujo nome da empresa não é indefinido (ou seja, não é um `null` valor) ou Microsoft.	OBTER`~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true`^**
Listar todos os usuários cujo nome da empresa seja indefinido ou Microsoft.	OBTER`~/users?$filter=companyName in (null, 'Microsoft')&$count=true`^**
Use a conversão OData para obter uma participação transitória em grupos com um nome de exibição que comece com “a”, incluindo o número de objetos retornados.	OBTER`~/me/transitiveMemberOf/microsoft.graph.group?$count=true&$filter=startswith(displayName, 'a')`^**

Sintaxe para usar o parâmetro de consulta OData de filtro

O artigo a seguir demonstra a sintaxe para usar o $filter parâmetro de consulta OData e seus operadores associados. Os exemplos são fornecidos apenas para orientação e não refletem uma lista abrangente para a aplicação de $filter.

Observação

Os valores GUID e DateTimeOffset não estão entre aspas em $filter expressões.

^** : este exemplo só tem suporte com recursos avançados de consulta.

Para tipos primitivos únicos, como String, Int e datas

Operador	Sintaxe
`eq`	`~/users?$filter=userType eq 'Member'` `~/groups?$filter=isAssignableToRole eq true`
`not`	`~/users?$filter=not(userType eq 'Member')`^**
`ne`	`~/users?$filter=companyName ne null`^ `~/groups?$filter=isAssignableToRole ne true`^
`startswith`	`~/users?$filter=startswith(userPrincipalName, 'admin')`
`endswith`	`~/users?$filter=endswith(mail,'@outlook.com')`^**
`in`	`~/users?$filter=mail in ('mail1@domain.com', 'mail2@domain.com')` Observação: Consulte Limitações de parâmetros de consulta nos problemas conhecidos para obter limitações para `in` e `eq` operadores.
`le`	`~/devices?$filter=registrationDateTime le 2021-01-02T12:00:00Z`^**
`ge`	`~/devices?$filter=registrationDateTime ge 2021-01-02T12:00:00Z`^**
`not` e `endswith`	`~/users?$filter=not(endswith(mail, 'contoso.com'))`^**
`not` e `startswith`	`~/users?$filter=not(startswith(mail, 'A'))`^**
`not` e `eq`	`~/users?$filter=not(companyName eq 'Contoso E.A.')`^**
`not` e `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 obter uma coleção de tipos primitivos

Operador (s)	Sintaxe
`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` e `endswith`	`~/groups?$filter=not(endswith(mail,'contoso.com'))`^**
`not` e `startswith`	`~/groups?$filter=not(startswith(mail,'Pineview'))`^**
`not` e `eq`	`~/groups?$filter=not(mail eq 'PineviewSchoolStaff@Contoso.com')`^**
`eq` e `$count` para coleções vazias	`~/users?$filter=assignedLicenses/$count eq 0`^**
`ne` e `$count` para coleções vazias	`~/users?$filter=assignedLicenses/$count ne 0`^**
`not` e `$count` para coleções vazias	`~/users?$filter=not(assignedLicenses/$count eq 0)`^**
`$count` para coleções com um único objeto	`~/servicePrincipals?$filter=owners/$count eq 1`^**

Para tipos GUID

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

Para obter uma coleção de tipos de GUID

Operador (s)	Sintaxe
`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 uma coleção de tipos complexos

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

Recursos avançados de consulta em objetos de diretório

Comentários

Esta página foi útil?

Last updated on 2026-08-24