Recursos avançados de consulta em objetos Microsoft Entra ID
Artigo
À 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";
});
// 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";
});
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");
});
// 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");
});
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:
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 .
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.
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:
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.
// 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();
<?php
use Microsoft\Graph\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$graphServiceClient->users()->count()->get()->wait();
{
"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\"";
});
// 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\"";
});
{
"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,'";
});
// 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,'";
});
{
"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");
});
// 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");
});
{
"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;
});
// 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;
});
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.