Utilizar o parâmetro de consulta $filter

Artigo
07/04/2024

O Microsoft Graph suporta o $filter parâmetro de consulta OData para obter um subconjunto de uma coleção.

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

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

Operadores e funções suportados em expressões de filtro

O Microsoft Graph suporta a utilização dos seguintes operadores e funções. No entanto, o suporte por recursos individuais e as respetivas propriedades ou relações podem variar. Além disso, algumas propriedades e relações suportam $filter apenas consultas avançadas. Veja a documentação de recursos específica para obter detalhes e Sintaxe para utilizar o parâmetro de consulta OData de filtro para obter exemplos de como utilizar estes operadores e funções.

Tipo de operador	Operador
Operadores de igualdade	Igual a (`eq`) Não é igual a (`ne`) Negação lógica (`not`) Em (`in`) Tem (`has`) Nota: Ao utilizar o `in` operador , o pedido está limitado a 15 expressões na cláusula de filtro por predefinição ou um comprimento de URL de 2048 carateres ao utilizar capacidades de consulta avançadas.
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 e all para avaliar correspondências em propriedades de valores múltiplos, ou seja, uma coleção de valores primitivos, como Tipos de cadeia ou coleção de recursos.

Operador `any`

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

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

Em que

collection é 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. Esta variável pode ter o nome quase tudo, por exemplo, p:p.
a subPropriedade é necessária quando a consulta se aplica a uma coleção de entidades. Representa a propriedade do tipo complexo cujo valor está a corresponder.
value-to-match representa o membro da coleção com o qual está a corresponder.

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 de Cadeia. A consulta seguinte obtém apenas utilizadores 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://video2.skills-academy.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')";
});



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://video2.skills-academy.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://video2.skills-academy.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 seguinte obtém apenas os utilizadores 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://video2.skills-academy.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)";
});



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://video2.skills-academy.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://video2.skills-academy.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 seguinte obtém apenas os utilizadores a quem não foi atribuído 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://video2.skills-academy.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");
});



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://video2.skills-academy.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://video2.skills-academy.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 devolve true se a expressão for true para todos os itens da coleção, caso contrário devolve false. Atualmente, não é suportado 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, veja o protocolo OData.

Observação

Os exemplos marcados com ^** só são suportados com capacidades de consulta avançadas.
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'`. NOTA: A propriedade dateTime da entidade do evento é um tipo de Cadeia.
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 utilizadores cujo nome da empresa não esteja indefinido (ou seja, não um `null` valor) ou a 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 utilizar o parâmetro de consulta OData de filtro

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

Observação

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

^** : este exemplo só é suportado com capacidades de consulta avançadas.

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

Operador	Sintaxe
`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: Para cadeias de consulta que utilizam `in` o operador, o pedido está limitado a 15 expressões na cláusula de filtro por predefinição ou um comprimento de URL de 2048 carateres ao utilizar capacidades de consulta avançadas.
`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 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 objeto	`~/servicePrincipals?$filter=owners/$count eq 1`^**

Para tipos de 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 uma coleção de tipos 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'))`^**

Capacidades avançadas de consulta em objetos de diretório

Compartilhar via

Utilizar o parâmetro de consulta $filter

Operadores e funções suportados em expressões de filtro

Filtrar usando operadores lambda

Operador `any`

Operador `all`

Exemplos usando o operador de consulta de filtro

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

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

Para uma coleção de tipos primitivos

Para tipos de GUID

Para uma coleção de tipos GUID

Para uma coleção de tipos complexos

Comentários

Recursos adicionais

Compartilhar via

Utilizar o parâmetro de consulta $filter

Operadores e funções suportados em expressões de filtro

Filtrar usando operadores lambda

Operador any

Operador all

Exemplos usando o operador de consulta de filtro

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

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

Para uma coleção de tipos primitivos

Para tipos de GUID

Para uma coleção de tipos GUID

Para uma coleção de tipos complexos

Conteúdo relacionado

Comentários

Recursos adicionais

Operador `any`

Operador `all`