Recursos avançados de consulta em objetos do Microsoft Entra ID

O Microsoft Graph dá suporte a recursos avançados de consulta em vários objetos do Microsoft Entra ID, também chamados de objetos de diretório, para ajudá-lo a acessar dados com eficiência. Os exemplos incluem a adição de operadores not (not), not equals (ne) e ends with (endsWith) no $filter parâmetro de consulta.

O mecanismo de consulta do Microsoft Graph usa um repositório de índice para atender às solicitações de consulta. Para adicionar suporte para recursos de consulta extras em algumas propriedades, essas propriedades são indexadas em um repositório separado. Essa indexação separada melhora o desempenho da consulta. No entanto, esses recursos avançados de consulta não estão disponíveis por padrão. O solicitante deve definir o cabeçalho eventualConsistencyLevelpara e, exceto para $search, usar o $count parâmetro de consulta. O cabeçalho ConsistencyLevel e $count são referidos como parâmetros de consulta avançados.

Por exemplo, para recuperar apenas contas de usuário inativas, você pode executar uma destas consultas que usam o $filter parâmetro de consulta:

Opção 1: Use o $filter parâmetro query com o eq operador. Essa solicitação funciona por padrão e não requer os parâmetros de consulta avançados.

GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled eq false


// 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 = "accountEnabled eq false";
});



// 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 := "accountEnabled eq false"

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 = "accountEnabled eq false";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('accountEnabled eq false')
	.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 = "accountEnabled eq false";
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "accountEnabled eq false"


# 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 = "accountEnabled eq false",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

Opção 2: Use o $filter parâmetro query com o ne operador. Não há suporte para essa solicitação por padrão porque o ne operador só tem suporte em consultas avançadas. Portanto, você deve adicionar o cabeçalho ConsistencyLevel definido eeventual usar a cadeia de caracteres de $count=true consulta.

GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled ne true&$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 = "accountEnabled ne true";
	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 := "accountEnabled ne true"
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 = "accountEnabled ne true";
	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('accountEnabled ne true')
	.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 = "accountEnabled ne true";
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "accountEnabled ne true" -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 = "accountEnabled ne true",
		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)

Objetos do Microsoft Entra ID (diretório) que dão suporte a recursos avançados de consulta

Os recursos avançados de consulta têm suporte apenas em objetos de diretório e suas relações, incluindo os seguintes objetos:

Objeto	Relações
administrativeUnit	membros
application	proprietários
appRoleAssignment	-
device	memberOf transitiveMemberOf registeredUsers registeredOwners
group	membros transitiveMembers memberOf transitiveMemberOf proprietários appRoleAssignments
oAuth2PermissionGrant (concessões de permissão delegadas)	-
orgContact	memberOf transitiveMemberOf
servicePrincipal	memberOf proprietários transitiveMemberOf appRoleAssignments appRoleAssignedTo oAuth2PermissionGrant
user	memberOf transitiveMemberOf ownedObjects registeredDevices ownedDevices transitiveManagers directReports transitiveReports appRoleAssignments oAuth2PermissionGrant

Observação

O uso de $filter nas relações da lista anterior de objetos de diretório tem suporte apenas com parâmetros de consulta avançados. No entanto, nesses casos, não use $expand na mesma solicitação porque não há suporte com parâmetros de consulta avançados.

Cenários de consulta que exigem recursos avançados de consulta

A tabela a seguir lista cenários de consulta em objetos de diretório compatíveis com consultas avançadas:

Descrição	Exemplo
Usar `$count` como um segmento URL	OBTER`~/groups/$count`
Usar o `$count` como parâmetro consultar cadeia de caracteres	OBTER`~/servicePrincipals?$count=true`
Uso de `$count` em uma expressão `$filter`	OBTER`~/users?$filter=assignedLicenses/$count eq 0&$count=true`
Usar de `$search`	OBTER`~/applications?$search="displayName:Browser"`
Usar `$orderby` em propriedades selecionadas	OBTER`~/applications?$orderby=displayName&$count=true`
Usar o `$filter` com o `endsWith` operador	OBTER`~/users?$count=true&$filter=endsWith(mail,'@outlook.com')`
Usar o `$filter` e `$orderby` na mesma consulta	OBTER`../applications?$orderby=displayName&$filter=startsWith(displayName, 'Box')&$count=true`
Uso o `$filter` com os `startsWith` operadores em propriedades específicas.	OBTER`~/users?$filter=startsWith(mobilePhone, '25478') OR startsWith(mobilePhone, '25473')&$count=true`
Usar o `$filter` com `ne` e `not` operadores	OBTER`~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true`
Usar o `$filter` com `not` e `startsWith` operadores	OBTER`~/users?$filter=NOT startsWith(displayName, 'Conf')&$count=true`
Uso de `$filter` em uma coleção com o operador `endsWith`	OBTER`~/users?$count=true&$filter=proxyAddresses/any (p:endsWith(p, 'contoso.com'))&$select=id,displayName,proxyaddresses`
Uso de conversão de OData com lista de membros transitivos	OBTER`~/me/transitiveMemberOf/microsoft.graph.group?$count=true`

Observação

Você pode usar $filter e $orderby em conjunto somente com consultas avançadas.
No momento, as consultas avançadas não dão suporte a $expand.
No momento, os locatários do Azure AD B2C não dão suporte a recursos avançados de consulta.
Para usar recursos avançados de consulta em solicitações em lote, especifique o cabeçalho ConsistencyLevel na propriedade da POST solicitação JSON.

Suporte para filtrar por propriedades de objetos do Microsoft Entra ID (diretório)

As propriedades dos objetos de diretório se comportam de forma diferente em seu suporte aos parâmetros de consulta. Os cenários a seguir são comuns para objetos de diretório:

O operador in é suportado por padrão sempre que o operador eq for suportado por padrão.
O endswith operador é compatível apenas com parâmetros de consulta avançados e apenas pelas propriedades mail, otherMails, userPrincipalName e proxyAddresses .
Obter coleções vazias (/$count eq 0, /$count ne 0) e coleções com menos de um objeto (/$count eq 1, /$count ne 1) é suportado apenas com parâmetros de consulta avançados.
Os not operadores de negação and ne têm suporte apenas com parâmetros de consulta avançados.
- Todas as propriedades que dão suporte ao operador também dão suporte aos eqne operadores ou not .
- Para consultas que utilizam o any operador lambda, usar o not operador. Veja Filtrar utilizando operadores lambda.

As tabelas a seguir resumem o suporte para operadores por $filter propriedades de objetos de diretório e indicam onde há suporte para consultas por meio de recursos avançados de consulta.

Legenda

O $filter operador funciona por padrão para essa propriedade.
O $filter operador só funciona sem parâmetros de consulta avançados.
O $filter operador requerparâmetros de consulta avançados, que são:
- ConsistencyLevel=eventual cabeçalho
- $count=true cadeia de caracteres
Não há suporte para o $filter operador nessa propriedade. Envie-nos comentários para solicitar que esta propriedade suporte $filter para seus cenários.
Células em branco indicam que a consulta não é válida para essa propriedade.
A coluna de valor nulo indica que a propriedade pode ser anulada e filtrada usando null.
As propriedades que não estão listadas aqui não $filter oferecem suporte algum.

Propriedades da unidade administrativa

Propriedade	eq	startsWith	eq Null
description
displayName
isMemberManagementRestricted
membershipRule
membershipRuleProcessingState

Propriedades do aplicativo

Propriedade	eq	startsWith	ge/le	eq Null
appId
createdDateTime
description
disabledByMicrosoftStatus
displayName
federatedIdentityCredentials/any(f:f/issuer)
federatedIdentityCredentials/any(f:f/name)
federatedIdentityCredentials/any(f:f/subject)
identifierUris/any(p:p)
info/logoUrl
info/termsOfServiceUrl
notes
publicClient/redirectUris/any(p:p)
publisherDomain
requiredResourceAccess/any(r:r/resourceAppId)
referênciaDeGerenciamentoDeServiços
signInAudience
spa/redirectUris/any(p:p)
tags/any(p:p)
Nome único
verifiedPublisher/displayName
web/homePageUrl
web/redirectUris/any(p:p)

As propriedades a seguir da entidade de aplicativo dão suporte $count a uma coleção em uma expressão de filtro.

Propriedade	eq Contagem 0	eq Contagem 1
extensionProperties/$count
federatedIdentityCredentials/$count

Propriedades do contrato

Propriedade	eq	startsWith
customerId
defaultDomainName
displayName

Propriedades do dispositivo

Propriedade	eq	startsWith	ge/le	eq Null
accountEnabled
alternativeSecurityIds/any(a:a/identityProvider)
alternativeSecurityIds/any(a:a/type)
approximateLastSignInDateTime
deviceCategory
deviceId
deviceOwnership
displayName
enrollmentProfileName
extensionAttributes/extensionAttribute1-15
hostnames/any(p:p)
isCompliant
isManaged
isRooted
managementType
fabricante
mdmAppId
modelo
onPremisesLastSyncDateTime
onPremisesSecurityIdentifier
onPremisesSyncEnabled
operatingSystem
operatingSystemVersion
physicalIds/any(p:p)
profileType
registrationDateTime
trustType

As propriedades a seguir da entidade de dispositivo dão suporte $count a uma coleção em uma expressão de filtro.

Propriedade	eq Contagem 0	eq Contagem 1
physicalIds/$count
systemLabels/$count

Propriedades de função de diretório

Propriedade	eq	startsWith	eq Null
description
displayName
roleTemplateId

Propriedades do grupo

Propriedade	eq	startsWith	ge/le	eq Null
assignedLicenses/any(a:a/skuId)
classificação
createdByAppId
createdDateTime
description
displayName
expirationDateTime
groupTypes/any(p:p)
hasMembersWithLicenseErrors
infoCatalogs/any(p:p)
isAssignableToRole
Email
mailEnabled
mailNickname
membershipRule
membershipRuleProcessingState
onPremisesLastSyncDateTime
onPremisesProvisioningErrors/any(o:o/category)
onPremisesProvisioningErrors/any(o:o/propertyCausingError)
onPremisesSamAccountName
onPremisesSecurityIdentifier
onPremisesSyncEnabled
preferredLanguage
proxyAddresses/any(p:p)
renewedDateTime
resourceBehaviorOptions/any(p:p)
resourceProvisioningOptions/any(p:p)
securityEnabled
Nome único

As propriedades a seguir da entidade do grupo dão suporte $count a uma coleção em uma expressão de filtro.

Propriedade	eq Contagem 0	eq Contagem 1
assignedLicenses/$count
onPremisesProvisioningErrors/$count
proxyAddresses/$count

Propriedades de contato organizacional

Propriedade	eq	startsWith	ge/le	eq Null
CompanyName
department
displayName
givenName
jobTitle
Email
mailNickname
manager/id
onPremisesLastSyncDateTime
onPremisesProvisioningErrors/any(o:o/category)
onPremisesProvisioningErrors/any(o:o/propertyCausingError)
onPremisesSyncEnabled
proxyAddresses/any(p:p)
surname

As seguintes propriedades da entidade orgContact dão suporte $count a uma coleção em uma expressão de filtro.

Propriedade	eq Contagem 0	eq Contagem 1
onPremisesProvisioningErrors/$count
proxyAddresses/$count

Propriedades da entidade de serviço

Propriedade	eq	startsWith	ge/le	eq Null
accountEnabled
alternativeNames/any(p:p)
appId
appOwnerOrganizationId
appRoleAssignmentRequired
applicationTemplateId
claimsPolicy/id
createdObjects/any(c:c/id)
description
displayName
federatedIdentityCredentials/any(f:f/issuer)
federatedIdentityCredentials/any(f:f/name)
federatedIdentityCredentials/any(f:f/subject)
homepage
info/logoUrl
info/termsOfServiceUrl
notes
preferredSingleSignOnMode
preferredTokenSigningKeyEndDateTime
publisherName
remoteDesktopSecurityConfiguration/id
servicePrincipalNames/any(p:p)
servicePrincipalType
tags/any(p:p)
verifiedPublisher/displayName

As seguintes propriedades da entidade servicePrincipal dão suporte $count a uma coleção em uma expressão de filtro.

Propriedade	eq Contagem 0	eq Contagem 1
federatedIdentityCredentials/$count

Propriedades de usuário

Propriedade	eq	startsWith	ge/le	eq Null
accountEnabled
ageGroup
assignedLicenses/any(a:a/skuId)
assignedPlans/any(a:a/capabilityStatus)
assignedPlans/any(a:a/service)
assignedPlans/any(a:a/servicePlanId)
authorizationInfo/certificateUserIds/any(p:p)
businessPhones/any(p:p)
city
em nuvemRealtimeCommunicationInfo/isSipEnabled
CompanyName
consentProvidedForMinor
country
createdDateTime
createdObjects/any(c:c/id)
creationType
department
displayName
employeeHireDate
employeeId
employeeOrgData/costCenter
employeeOrgData/division
employeeType
externalUserState
FaxNumber
givenName
identities/any(i:i/issuer)
imAddresses/any(p:p)
infoCatalogs/any(p:p)
isLicenseReconciliationNeeded
isResourceAccount
jobTitle
Email
mailNickname
mobilePhone
officeLocation
onPremisesDistinguishedName
onPremisesExtensionAttributes/extensionAttribute1-15
onPremisesImmutableId
onPremisesLastSyncDateTime
onPremisesProvisioningErrors/any(o:o/category)
onPremisesProvisioningErrors/any(o:o/propertyCausingError)
onPremisesSamAccountName
onPremisesSecurityIdentifier
onPremisesSipInfo/isSipEnabled
onPremisesSyncEnabled
otherMails/any(p:p)
passwordPolicies
passwordProfile/forceChangePasswordNextSignIn
passwordProfile/forceChangePasswordNextSignInWithMfa
postalCode
preferredLanguage
provisionedPlans/any(p:p/provisioningStatus)
provisionedPlans/any(p:p/service)
proxyAddresses/any(p:p)
state
streetAddress
surname
usageLocation
userPrincipalName
userType

As seguintes propriedades da entidade de usuário suportam $count uma coleção em uma expressão de filtro.

Propriedade	eq Contagem 0	eq Contagem 1
assignedLicenses/$count
onPremisesProvisioningErrors/$count
otherMails/$count
ownedObjects/$count
proxyAddresses/$count

A tabela a seguir mostra o suporte para $filter outras propriedades de extensão no objeto de usuário .

Tipo de extensão	eq	startsWith	eq null
Extensões de esquema
Extensões abertas
Extensões de diretório

Suporte para classificação por propriedades de objetos do Microsoft Entra ID (diretório)

A tabela a seguir resume o suporte para $orderby propriedades by de objetos de diretório e indica onde há suporte para a classificação por meio de recursos avançados de consulta.

Legenda

O $orderby operador funciona por padrão para essa propriedade.
O $orderby operador requerparâmetros de consulta avançados, que são:
- ConsistencyLevel=eventual cabeçalho
- $count=true cadeia de caracteres
O uso de e $orderby na mesma consulta para objetos de $filter diretório sempre requer parâmetros de consulta avançados. Para obter mais informações, consulte Cenários de consulta que exigem recursos avançados de consulta.

Objeto de diretório	Nome da propriedade	$orderby
administrativeUnit	createdDateTime
administrativeUnit	deletedDateTime
administrativeUnit	displayName
aplicação	createdDateTime
aplicação	deletedDateTime
aplicação	displayName
orgContact	createdDateTime
orgContact	displayName
device	approximateLastSignInDateTime
device	createdDateTime
device	deletedDateTime
device	displayName
group	createdDateTime
group	deletedDateTime
group	displayName
servicePrincipal	createdDateTime
servicePrincipal	deletedDateTime
servicePrincipal	displayName
usuário	createdDateTime
usuário	deletedDateTime
usuário	displayName
usuário	userPrincipalName
[todos os outros]	[todos os outros]

Tratamento de erros para consultas avançadas sobre objetos de diretório

A seção a seguir fornece exemplos de cenários de erro comuns quando você não usa parâmetros de consulta avançados quando necessário.

Você só pode contar objetos de diretório usando os parâmetros de consultas avançadas. Se você não especificar o ConsistencyLevel=eventual cabeçalho, a solicitação retornará um erro quando você usar o $count segmento de URL (/$count) ou ignorará silenciosamente o $count parâmetro de consulta (?$count=true) se você usá-lo.

GET https://graph.microsoft.com/v1.0/users/$count


// 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
await graphClient.Users.Count.GetAsync();



// 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"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Users().Count().Get(context.Background(), nil)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

graphClient.users().count().get();


const options = {
	authProvider,
};

const client = Client.init(options);

let int32 = await client.api('/users/$count')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


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


$graphServiceClient->users()->count()->get()->wait();


Import-Module Microsoft.Graph.Users

Get-MgUserCount


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

await graph_client.users.count.get()

{
    "error": {
        "code": "Request_BadRequest",
        "message": "$count is not currently supported.",
        "innerError": {
            "date": "2021-05-18T19:03:10",
            "request-id": "d9bbd4d8-bb2d-44e6-99a1-71a9516da744",
            "client-request-id": "539da3bd-942f-25db-636b-27f6f6e8eae4"
        }
    }
}

Para objetos de diretório, $search funciona apenas em consultas avançadas. Se você não especificar o cabeçalho ConsistencyLevel , a solicitação retornará um erro.

GET https://graph.microsoft.com/v1.0/applications?$search="displayName:Browser"


// 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.Applications.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Search = "\"displayName:Browser\"";
});



// 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"
	  graphapplications "github.com/microsoftgraph/msgraph-sdk-go/applications"
	  //other-imports
)


requestSearch := "\"displayName:Browser\""

requestParameters := &graphapplications.ApplicationsRequestBuilderGetQueryParameters{
	Search: &requestSearch,
}
configuration := &graphapplications.ApplicationsRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
applications, err := graphClient.Applications().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ApplicationCollectionResponse result = graphClient.applications().get(requestConfiguration -> {
	requestConfiguration.queryParameters.search = "\"displayName:Browser\"";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let applications = await client.api('/applications')
	.search('displayName:Browser')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Applications\ApplicationsRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new ApplicationsRequestBuilderGetRequestConfiguration();
$queryParameters = ApplicationsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->search = "\"displayName:Browser\"";
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Applications

Get-MgApplication -Search '"displayName:Browser"'


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.applications.applications_request_builder import ApplicationsRequestBuilder
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 = ApplicationsRequestBuilder.ApplicationsRequestBuilderGetQueryParameters(
		search = "\"displayName:Browser\"",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

{
    "error": {
        "code": "Request_UnsupportedQuery",
        "message": "Request with $search query parameter only works through MSGraph with a special request header: 'ConsistencyLevel: eventual'",
        "innerError": {
            "date": "2021-05-27T14:26:47",
            "request-id": "9b600954-ba11-4899-8ce9-6abad341f299",
            "client-request-id": "7964ef27-13a3-6ca4-ed7b-73c271110867"
        }
    }
}

Se uma propriedade ou parâmetro de consulta na URL der suporte apenas a consultas avançadas, mas o cabeçalho ConsistencyLevel ou a $count=true cadeia de caracteres de consulta estiver ausente, a solicitação retornará um erro.

GET https://graph.microsoft.com/beta/users?$filter=endsWith(userPrincipalName,'%23EXT%23@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 = "endsWith(userPrincipalName,'";
});



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

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


requestFilter := "endsWith(userPrincipalName,'"

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 = "endsWith(userPrincipalName,'";
});

Snippet not available


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


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

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "endsWith(userPrincipalName,'";
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Beta.Users

Get-MgBetaUser -Filter "endsWith(userPrincipalName,'"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.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 = "endsWith(userPrincipalName,'",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

{
    "error": {
        "code": "Request_UnsupportedQuery",
        "message": "Operator 'endsWith' is not supported because the required parameters might be missing. Try adding $count=true query parameter and ConsistencyLevel:eventual header. Refer to https://aka.ms/graph-docs/advanced-queries for more information",
        "innerError": {
            "date": "2023-07-14T08:43:39",
            "request-id": "b3731da7-5c46-4c37-a8e5-b190124d2531",
            "client-request-id": "a1556ddf-4794-929d-0105-b753a78b4c68"
        }
    }
}

Se uma propriedade não for indexada para dar suporte a um parâmetro de consulta, a solicitação retornará um erro mesmo que parâmetros de consulta avançados sejam especificados. Por exemplo, a propriedade createdDateTime do recurso de grupo não é indexada para recursos de consulta.

GET https://graph.microsoft.com/beta/groups?$filter=createdDateTime ge 2021-11-01&$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.Groups.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "createdDateTime ge 2021-11-01";
	requestConfiguration.QueryParameters.Count = true;
	requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});



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

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

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


requestFilter := "createdDateTime ge 2021-11-01"
requestCount := true

requestParameters := &graphgroups.GroupsRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
	Count: &requestCount,
}
configuration := &graphgroups.GroupsRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
groups, err := graphClient.Groups().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

GroupCollectionResponse result = graphClient.groups().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "createdDateTime ge 2021-11-01";
	requestConfiguration.queryParameters.count = true;
	requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});


const options = {
	authProvider,
};

const client = Client.init(options);

let groups = await client.api('/groups')
	.version('beta')
	.header('ConsistencyLevel','eventual')
	.filter('createdDateTime ge 2021-11-01')
	.get();


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Groups\GroupsRequestBuilderGetRequestConfiguration;


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

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

$queryParameters = GroupsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "createdDateTime ge 2021-11-01";
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Beta.Groups

Get-MgBetaGroup -Filter "createdDateTime ge 2021-11-01" -CountVariable CountVar  -ConsistencyLevel eventual


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.groups.groups_request_builder import GroupsRequestBuilder
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 = GroupsRequestBuilder.GroupsRequestBuilderGetQueryParameters(
		filter = "createdDateTime ge 2021-11-01",
		count = True,
)

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


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

{
    "error": {
        "code": "Request_UnsupportedQuery",
        "message": "Unsupported or invalid query filter clause specified for property 'createdDateTime' of resource 'Group'.",
        "innerError": {
            "date": "2023-07-14T08:42:44",
            "request-id": "b6a5f998-94c8-430d-846d-2eaae3031492",
            "client-request-id": "2be83e05-649e-2508-bcd9-62e666168fc8"
        }
    }
}

No entanto, uma solicitação que inclui parâmetros de consulta pode falhar silenciosamente. Por exemplo, a solicitação pode falhar para parâmetros de consulta sem suporte e para combinações sem suporte de parâmetros de consulta. Nesses casos, examine os dados retornados pela solicitação para determinar se os parâmetros de consulta especificados surtiram o efeito desejado. Por exemplo, no exemplo a seguir, falta o parâmetro @odata.count mesmo que a consulta seja bem sucedida.

GET https://graph.microsoft.com/v1.0/users?$count=true


// 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.Count = true;
});



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


requestCount := true

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Count: &requestCount,
}
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.count = true;
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.get();


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


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

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Users

Get-MgUser -CountVariable CountVar


# 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(
		count = True,
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "value":[
    {
      "displayName":"Oscar Ward",
      "mail":"oscarward@contoso.com",
      "userPrincipalName":"oscarward@contoso.com"
    }
  ]
}

Comentários

Esta página foi útil?

Last updated on 2026-08-24

Recursos avançados de consulta em objetos do Microsoft Entra ID

Objetos do Microsoft Entra ID (diretório) que dão suporte a recursos avançados de consulta

Cenários de consulta que exigem recursos avançados de consulta

Suporte para filtrar por propriedades de objetos do Microsoft Entra ID (diretório)

Legenda

Propriedades da unidade administrativa

Propriedades do aplicativo

Propriedades do contrato

Propriedades do dispositivo

Propriedades de função de diretório

Propriedades do grupo

Propriedades de contato organizacional

Propriedades da entidade de serviço

Propriedades de usuário

Suporte para classificação por propriedades de objetos do Microsoft Entra ID (diretório)

Legenda

Tratamento de erros para consultas avançadas sobre objetos de diretório

Conteúdo relacionado

Comentários

Recursos adicionais