Recursos avançados de consulta em objetos Microsoft Entra ID

Artigo
04/16/2024

À medida que Microsoft Entra continua fornecendo mais recursos e melhorias em estabilidade, disponibilidade e desempenho, o Microsoft Graph também continua a evoluir e escalar para acessar os dados com eficiência. Uma maneira é por meio do suporte crescente do Microsoft Graph para recursos avançados de consulta em vários objetos Microsoft Entra ID, também chamados de objetos de diretório e suas 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. Essa indexação separada permite que Microsoft Entra ID aumente o suporte e melhore o desempenho das solicitações de consulta. No entanto, esses recursos avançados de consulta não estão disponíveis por padrão, mas o solicitante também deve definir o cabeçalho ConsistencyLevel como eventuale, exceto para $search, use 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: Use o $filter parâmetro de consulta com o eq operador. Essa solicitação funciona por padrão, ou seja, a solicitação 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";
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "accountEnabled eq false"



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestFilter := "accountEnabled eq false"

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

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

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "accountEnabled eq false",
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

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

Opção 2: Use o $filter parâmetro de consulta com o ne operador. Essa solicitação não tem suporte por padrão porque o ne operador só tem suporte em consultas avançadas. Portanto, você deve adicionar o conjunto de cabeçalho eventualConsistencyLevele usar a $count=true cadeia de caracteres 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");
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "accountEnabled ne true" --count "true" --consistency-level "eventual"



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
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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

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

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "accountEnabled ne true",
		count = True,
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
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 dão suporte a recursos avançados de consulta

Essas funcionalidades avançadas de consulta têm suporte apenas em objetos de diretório e suas relações, incluindo os seguintes objetos usados com frequência:

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 exigem recursos avançados de consulta

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 filtro por propriedades de objetos 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 com suporte por padrã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 tem suporte apenas com parâmetros de consulta avançados por email, outras propriedadesMails, 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) é compatível apenas com parâmetros de consulta avançados.
Os not operadores de negação e ne têm suporte apenas com parâmetros de consulta avançados.
- Todas as propriedades que dão suporte ao eq operador também dão suporte aos ne 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 $filter operadores por propriedades de objetos de diretório e indicam onde há suporte para consulta por meio de recursos avançados de consulta.

Legenda

O $filter operador funciona por padrã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 tem suporte 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 dão suporte $filter .

Propriedades da unidade administrativa

Propriedade	eq	startsWith	eq Null
description
displayName
isMemberManagementRestricted
membershipRule
membershipRuleProcessingState
scopedRoleMembers/any(s:s/id)

Propriedades do aplicativo

Propriedade	eq	startsWith	ge/le	eq Null
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 propriedades a seguir da entidade de aplicativo dão suporte $count a uma coleção em uma expressão de filtro.

Propriedade	eq Count 0	eq Count 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 Count 0	eq Count 1
physicalIds/$count
systemLabels/$count

Propriedades da função de diretório

Propriedade	eq	startsWith	eq Null
description
displayName
roleTemplateId

Propriedades do grupo

Propriedade	eq	startsWith	ge/le	eq Null
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
configurações/any(s:s/displayName)
configurações/any(s:s/id)
Nome único

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

Propriedade	eq Count 0	eq Count 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 propriedades a seguir da entidade orgContact dão suporte $count a uma coleção em uma expressão de filtro.

Propriedade	eq Count 0	eq Count 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
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 propriedades a seguir da entidade servicePrincipal dão suporte $count a uma coleção em uma expressão de filtro.

Propriedade	eq Count 0	eq Count 1
federatedIdentityCredentials/$count
ownedObjects/$count

Propriedades de usuário

Propriedade	eq	startsWith	ge/le	eq Null
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 propriedades a seguir da entidade de usuário dão suporte $count a uma coleção em uma expressão de filtro.

Propriedade	eq Count 0	eq Count 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 do 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 Microsoft Entra ID (diretório)

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

Legenda

O $orderby operador funciona por padrã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
O uso de $filter e $orderby na mesma consulta para objetos de 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	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, a solicitação retornará um erro quando o $count segmento de URL for usado ou ignorar silenciosamente o $count parâmetro de consulta (?$count=true) se ele for usado.

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


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users count get



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



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


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc applications list --search ""displayName:Browser""



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphapplications "github.com/microsoftgraph/msgraph-sdk-go/applications"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



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

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

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

graph_client = GraphServiceClient(credentials, scopes)

query_params = ApplicationsRequestBuilder.ApplicationsRequestBuilderGetQueryParameters(
		search = "\"displayName:Browser\"",
)

request_configuration = ApplicationsRequestBuilder.ApplicationsRequestBuilderGetRequestConfiguration(
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,'";
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta users list --filter "endsWith(userPrincipalName,'"



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestFilter := "endsWith(userPrincipalName,'"

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

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\GraphServiceClient;
use Microsoft\Graph\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 import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "endsWith(userPrincipalName,'",
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
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 dar suporte a um parâmetro de consulta, mesmo que os parâmetros de consulta avançados sejam especificados, a solicitação retornará 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");
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta groups list --filter "createdDateTime ge 2021-11-01" --count "true" --consistency-level "eventual"



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
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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

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\GraphServiceClient;
use Microsoft\Graph\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 import GraphServiceClient
from msgraph.generated.groups.groups_request_builder import GroupsRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = GroupsRequestBuilder.GroupsRequestBuilderGetQueryParameters(
		filter = "createdDateTime ge 2021-11-01",
		count = True,
)

request_configuration = GroupsRequestBuilder.GroupsRequestBuilderGetRequestConfiguration(
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, 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 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;
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --count "true"



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestCount := true

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Count: &requestCount,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

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

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		count = True,
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
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"
    }
  ]
}

Recursos avançados de consulta em objetos Microsoft Entra ID

Microsoft Entra ID objetos (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 filtro por propriedades de objetos 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 classificação por propriedades de objetos Microsoft Entra ID (diretório)

Legenda

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

Comentários

Comentários

Recursos adicionais

Recursos avançados de consulta em objetos Microsoft Entra ID

Microsoft Entra ID objetos (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 filtro por propriedades de objetos 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 classificação por propriedades de objetos 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