Capacidades avançadas de consulta em objetos Microsoft Entra ID

O Microsoft Graph suporta capacidades de consulta avançadas em vários objetos de Microsoft Entra ID, também denominados objetos de diretório, para o ajudar a aceder a dados de forma eficiente. Os exemplos incluem a adição de não (not), não é igual a (ne) e termina com operadores (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 capacidades de consulta adicionais em algumas propriedades, essas propriedades são indexadas num arquivo separado. Esta indexação separada melhora o desempenho das consultas. No entanto, estas capacidades avançadas de consulta não estão disponíveis por predefinição. O requerente tem de definir o cabeçalho ConsistencyLevel como eventuale, exceto para $search, utilize 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 obter apenas contas de utilizador inativas, pode executar qualquer uma destas consultas que utilizam o $filter parâmetro de consulta:

Opção 1: Utilize o $filter parâmetro de consulta com o eq operador . Este pedido funciona por predefiniçã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: Utilize o $filter parâmetro de consulta com o ne operador . Este pedido não é suportado por predefinição porque o ne operador só é suportado em consultas avançadas. Por conseguinte, tem de adicionar o cabeçalho ConsistencyLevel definido a eventuale utilizar a $count=true cadeia de 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)

Microsoft Entra ID objetos (diretório) que suportam capacidades de consulta avançadas

As capacidades avançadas de consulta são suportadas apenas em objetos de diretório e respetivas 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

A utilização de $filter nas relações da lista anterior de objetos de diretório é suportada apenas com parâmetros de consulta avançados. No entanto, nesses casos, não utilize $expand no mesmo pedido porque não é suportado com parâmetros de consulta avançados.

Cenários de consulta que requerem capacidades de consulta avançadas

A tabela seguinte lista cenários de consulta em objetos de diretório que as consultas avançadas suportam:

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

Só pode utilizar $filter e $orderby em conjunto com consultas avançadas.
As consultas avançadas não suportam $expandatualmente .
Azure AD inquilinos B2C não suportam atualmente capacidades de consulta avançadas.
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 de 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 só é suportado com parâmetros de consulta avançados e apenas pelas propriedades mail, otherMails, userPrincipalName e proxyAddresses .
A obtenção de coleções vazias (/$count eq 0, /$count ne 0) e coleções com menos de um objeto (/$count eq 1, /$count ne 1) só é suportada com parâmetros de consulta avançados.
Os not operadores de negação e ne são suportados apenas com parâmetros de consulta avançados.
- Todas as propriedades que suportam o eq operador também suportam os ne operadores ou not .
- Para consultas que utilizam o any operador lambda, usar o not operador. Veja Filtrar utilizando operadores lambda.

As tabelas seguintes resumem o suporte para $filter operadores por propriedades de objetos de diretório e indicam onde a consulta é suportada através de capacidades de consulta avançadas.

Legenda

O $filter operador funciona por predefinição para essa propriedade.
O $filter operador só funciona sem parâmetros de consulta avançados.
O $filter operador requer parâmetrosde consulta avançados, que são:
- ConsistencyLevel=eventual cabeçalho
- $count=true cadeia de caracteres
O $filter operador não é suportado nessa propriedade. Envie-nos comentários para solicitar que esta propriedade suporte $filter para seus cenários.
As 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 suportam $filter de todo.

Propriedades da unidade administrativa

Propriedade	eq	startsWith	eq Nulo
description
displayName
isMemberManagementRestricted
membershipRule
membershipRuleProcessingState

Propriedades do aplicativo

Propriedade	eq	startsWith	ge/le	eq Nulo
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 seguintes propriedades da entidade da aplicação suportam $count uma coleção numa expressão de filtro.

Propriedade	Contagem de eq 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 Nulo
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 seguintes propriedades da entidade do dispositivo suportam $count uma coleção numa expressão de filtro.

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

Propriedades da função de diretório

Propriedade	eq	startsWith	eq Nulo
description
displayName
roleTemplateId

Propriedades do grupo

Propriedade	eq	startsWith	ge/le	eq Nulo
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 seguintes propriedades da entidade de grupo suportam $count uma coleção numa expressão de filtro.

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

Propriedades de contato organizacional

Propriedade	eq	startsWith	ge/le	eq Nulo
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 suportam $count uma coleção numa expressão de filtro.

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

Propriedades da entidade de serviço

Propriedade	eq	startsWith	ge/le	eq Nulo
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 suportam $count uma coleção numa expressão de filtro.

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

Propriedades de usuário

Propriedade	eq	startsWith	ge/le	eq Nulo
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
cloudRealtimeCommunicationInfo/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 do suporte $count da entidade de utilizador de uma coleção numa expressão de filtro.

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

A tabela seguinte mostra o suporte para $filter outras propriedades de extensão no objeto de utilizador .

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

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

A tabela seguinte resume o suporte para $orderby por propriedades de objetos de diretório e indica onde a ordenação é suportada através de capacidades de consulta avançadas.

Legenda

O $orderby operador funciona por predefinição para essa propriedade.
O $orderby operador requer parâmetrosde consulta avançados, que são:
- ConsistencyLevel=eventual cabeçalho
- $count=true cadeia de caracteres
A utilização de $filter e $orderby na mesma consulta para objetos de diretório requer sempre parâmetros de consulta avançados. Para obter mais informações, veja Cenários de consulta que requerem capacidades de consulta avançadas.

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 secção seguinte fornece exemplos de cenários de erro comuns quando não utiliza parâmetros de consulta avançados, sempre que necessário.

Só pode contar objetos de diretório com os parâmetros de consultas avançadas. Se não especificar o ConsistencyLevel=eventual cabeçalho, o pedido devolve um erro quando utiliza o $count segmento de URL (/$count) ou ignora silenciosamente o $count parâmetro de consulta (?$count=true) se o utilizar.

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 não especificar o cabeçalho ConsistencyLevel , o pedido devolve 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 no URL suportar apenas consultas avançadas, mas o cabeçalho ConsistencyLevel ou a $count=true cadeia de consulta estiverem em falta, o pedido devolve 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 estiver indexada para suportar um parâmetro de consulta, o pedido devolve um erro mesmo que sejam especificados parâmetros de consulta avançados. Por exemplo, a propriedade createdDateTime do recurso de grupo não está indexada para capacidades 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, um pedido que inclua parâmetros de consulta pode falhar automaticamente. Por exemplo, o pedido pode falhar para parâmetros de consulta não suportados e para combinações não suportadas de parâmetros de consulta. Nestes casos, examine os dados devolvidos pelo pedido para determinar se os parâmetros de consulta especificados tiveram 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"
    }
  ]
}

Feedback

Esta página foi útil?

Last updated on 2025-08-29

Partilhar via

Capacidades avançadas de consulta em objetos Microsoft Entra ID

Microsoft Entra ID objetos (diretório) que suportam capacidades de consulta avançadas

Cenários de consulta que requerem capacidades de consulta avançadas

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

Legenda

Propriedades da unidade administrativa

Propriedades do aplicativo

Propriedades do contrato

Propriedades do dispositivo

Propriedades da função de diretório

Propriedades do grupo

Propriedades de contato organizacional

Propriedades da entidade de serviço

Propriedades de usuário

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

Legenda

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

Conteúdo relacionado

Feedback

Recursos adicionais