Capacidades de consulta avançadas em objetos do Microsoft Entra ID

Artigo
05/31/2024

À medida que o Microsoft Entra continua a oferecer mais capacidades e melhorias na estabilidade, disponibilidade e desempenho, o Microsoft Graph também continua a evoluir e a dimensionar para aceder aos dados de forma eficiente. Uma forma é através do suporte crescente do Microsoft Graph para capacidades de consulta avançadas em vários objetos do Microsoft Entra ID, também denominados objetos de diretório e respetivas propriedades. Por exemplo, a adição de não (not), não é igual a (ne) e termina com (endsWith) operadores no parâmetro de consulta$filter.

O mecanismo de consulta do Microsoft Graph usa um repositório de índice para atender às solicitações de consulta. Para adicionar suporte as funcionalidades adicionais de consulta em algumas propriedades, essas propriedades agora são indexadas em um repositório separado. Esta indexação separada permite que o ID do Microsoft Entra aumente o suporte e melhore o desempenho dos pedidos de consulta. No entanto, estas capacidades avançadas de consulta não estão disponíveis por predefinição, mas o requerente também tem de definir o cabeçalho ConsistencyLevel para eventuale, exceto para $search, utilizar 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ários inativos, você pode executar qualquer uma destas consultas que utilizam o parâmetro de consulta $filter.

Opção 1: Utilize o $filter parâmetro de consulta com o eq operador . Este pedido funciona por predefinição, ou seja, o pedido 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";
});



mgc users list --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"


from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration

graph_client = GraphServiceClient(credentials, scopes)

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



mgc users list --filter "accountEnabled ne true" --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 := "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


from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration

graph_client = GraphServiceClient(credentials, scopes)

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 suportam capacidades de consulta avançadas

Estas capacidades avançadas de consulta são suportadas apenas em objetos de diretório e respetivas relações, incluindo os seguintes objetos utilizados frequentemente:

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 transitiveMemberOf appRoleAssignments appRoleAssignmentsTo oAuth2PermissionGrant
user	memberOf transitiveMemberOf ownedObjects registeredDevices ownedDevices transitiveManagers directReports transitiveReports appRoleAssignments oAuth2PermissionGrant

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

A tabela a seguir lista os cenários de consulta em objetos de diretório com suporte apenas em 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

O uso de $filter e $orderby juntos é suportado apenas em consultas avançadas.
$expand atualmente não é suportado em consultas avançadas.
As funcionalidades de consulta avançada não estão disponíveis no momento para locatários do Azure AD B2C.
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:

As consultas suportadas por predefinição também funcionarão com parâmetros de consulta avançados, mas a resposta será eventualmente consistente.
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 por correio, outras propriedadesMails, 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 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
scopedRoleMembers/any(s:s/id)

Propriedades do aplicativo

Propriedade	eq	startsWith	ge/le	eq Nulo
appId
createdDateTime
createdOnBehalfOf/id
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
appRoleAssignments/any(a:a/id)
assignedLicenses/any(a:a/skuId)
classificação
createdByAppId
createdOnBehalfOf/id
description
displayName
expirationDateTime
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
settings/any(s:s/displayName)
settings/any(s:s/id)
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
appRoleAssignedTo/any(a:a/id)
appRoleAssignmentRequired
appRoleAssignments/any(a:a/id)
applicationTemplateId
createdObjects/any(c:c/id)
delegatedPermissionClassifications/any(d:d/id)
description
displayName
federatedIdentityCredentials/any(f:f/issuer)
federatedIdentityCredentials/any(f:f/name)
federatedIdentityCredentials/any(f:f/subject)
homepage
info/logoUrl
info/termsOfServiceUrl
notes
oauth2PermissionGrants/any(o:o/id)
preferredSingleSignOnMode
preferredTokenSigningKeyEndDateTime
publisherName
remoteDesktopSecurityConfiguration/id
remoteDesktopSecurityConfiguration/targetDeviceGroups/any(t:t/displayName)
remoteDesktopSecurityConfiguration/targetDeviceGroups/any(t:t/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
ownedObjects/$count

Propriedades de usuário

Propriedade	eq	startsWith	ge/le	eq Nulo
accountEnabled
ageGroup
appRoleAssignments/any(a:a/id)
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
licenseDetails/any(l:l/id)
Email
mailNickname
manager/id
mobilePhone
oauth2PermissionGrants/any(o:o/id)
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)
scopedRoleMemberOf/any(s:s/id)
showInAddressList
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 do 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	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 contagem de objetos de diretório só é suportada usando os parâmetros de consultas avançados. Se o ConsistencyLevel=eventual cabeçalho não for especificado, o pedido devolve um erro quando o $count segmento de URL é utilizado ou ignora silenciosamente o $count parâmetro de consulta (?$count=true) se for utilizado.

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();



mgc users count get



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


from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


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 o cabeçalho ConsistencyLevel não for especificado, 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\"";
});



mgc applications list --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"'


from msgraph import GraphServiceClient
from msgraph.generated.applications.applications_request_builder import ApplicationsRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration

graph_client = GraphServiceClient(credentials, scopes)

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 for suportado apenas em consultas avançadas, mas o cabeçalho ConsistencyLevel ou a cadeia de caracteres $count=true estiver faltando, a solicitação retorna 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,'";
});



mgc-beta users list --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,'"


from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration

graph_client = GraphServiceClient(credentials, scopes)

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 tiver sido indexada para suportar um parâmetro de consulta, mesmo que os parâmetros de consulta avançados sejam especificados, o pedido devolve um erro.

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



mgc-beta groups list --filter "createdDateTime ge 2021-11-01" --count "true" --consistency-level "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


from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.groups.groups_request_builder import GroupsRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration

graph_client = GraphServiceClient(credentials, scopes)

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



mgc users list --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


from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration

graph_client = GraphServiceClient(credentials, scopes)

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"
    }
  ]
}

Compartilhar via

Capacidades de consulta avançadas em objetos do Microsoft Entra ID

Objetos do Microsoft Entra ID (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 do 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 do Microsoft Entra ID (diretório)

Legenda

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

Comentários

Comentários

Recursos adicionais

Compartilhar via

Capacidades de consulta avançadas em objetos do Microsoft Entra ID

Objetos do Microsoft Entra ID (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 do 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 do Microsoft Entra ID (diretório)

Legenda

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

Conteúdo relacionado

Comentários

Comentários

Recursos adicionais