Recursos avançados de consulta nos objetos do diretório Microsoft Azure Active Directory

Artigo
07/18/2022
8 minutos para o fim da leitura

Como o Microsoft Azure Active Directory continua a oferecer mais capacidades e melhorias na estabilidade, disponibilidade e desempenho, o Microsoft Graph também continua a evoluir e a escalar para acessar os dados de forma eficiente. Uma maneira é através do suporte crescente do Microsoft Graph para capacidades avançadas de consulta em vários objetos Microsoft Azure Active Directory 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 o Microsoft Azure AD aumente o suporte e melhore o desempenho das solicitações de consulta. No entanto, essas funcionalidades de consulta avançada não estão disponíveis por padrão, mas o solicitante também deve definir o cabeçalho ConsistencyLevel para eventual e, com exceção de $search, use o parâmetro de consulta $count. 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 parâmetro de consulta $filter com o operador eq. Esta solicitação funcionará 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

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=CS
var user = await graphClient.Users.Request()
    .Filter("accountEnabled eq false")
    .GetAsync();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Javascript
let users = await client.api('/users')
  .filter('accountEnabled eq false')
  .get();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Objective-C
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/users?$filter=accountEnabled eq false"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *usersDataTask = [httpClient dataTaskWithRequest:urlRequest
completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

  NSError *jsonError = nil;
  MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
  MSGraphUser *user = [[MSGraphUser alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[usersDataTask execute];

// See https://docs.microsoft.com/en-us/graph/sdks/create-client?tabs=Java
UserCollectionPage users = graphClient.users()
    .buildRequest()
    .filter("accountEnabled eq false")
    .get();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Go
requestParameters := &msgraphsdk.UsersRequestBuilderGetQueryParameters{
    Filter: "accountEnabled eq false",
}

options := &msgraphsdk.UsersRequestBuilderGetOptions{
    Q: requestParameters,
}

result, err := client.Users().Get(options)

Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "accountEnabled eq false"

Opção 2: Use o parâmetro de consulta $filter com o operador ne. Esta solicitação não é suportada por padrão porque o ne operador só é suportado em consultas avançadas. Portanto, você deve adicionar o ConsistencyLevel cabeçalho para eventuale usar a $count=true cadeia de caracteres.

GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled ne true&$count=true
ConsistencyLevel: eventual

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=CS
var user = await graphClient.Users.Request()
    .Request(new Option[] { new QueryOption("$count", "true")})
    .Header("ConsistencyLevel", "eventual")
    .Filter("accountEnabled ne true")
    .GetAsync();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Javascript
let users = await client.api('/users')
  .header('ConsistencyLevel','eventual')
  .filter('accountEnabled ne true')
  .count(true)
  .get();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Objective-C
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/users?$filter=accountEnabled ne true&$count=true"]]];
[urlRequest setHTTPMethod:@"GET"];
[urlRequest setValue:@"eventual" forHTTPHeaderField:@"ConsistencyLevel"];

MSURLSessionDataTask *usersDataTask = [httpClient dataTaskWithRequest:urlRequest
completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

  NSError *jsonError = nil;
  MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
  MSGraphUser *user = [[MSGraphUser alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[usersDataTask execute];

// See https://docs.microsoft.com/en-us/graph/sdks/create-client?tabs=Java
LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("ConsistencyLevel", "eventual"));
requestOptions.add(new QueryOption("$count", "true"))

UserCollectionPage users = graphClient.users()
    .buildRequest(requestOptions)
    .filter("accountEnabled ne true")
    .get();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Go
requestParameters := &msgraphsdk.UsersRequestBuilderGetQueryParameters{
    Filter: "accountEnabled ne true",
    Count: true,
}

headers := map[string]string{
    "ConsistencyLevel": "eventual"
}

options := &msgraphsdk.UsersRequestBuilderGetOptions{
    Q: requestParameters,
    H: headers,
}

result, err := client.Users().Get(options)

Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "accountEnabled ne true" -CountVariable CountVar -ConsistencyLevel eventual

Estas funcionalidades avançados de consulta são compatíveis somente com objetos de diretório do Microsoft Azure AD 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

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	GET `../groups/$count`
Usar o `$count` como parâmetro consultar cadeia de caracteres	GET `../servicePrincipals?$count=true`
Uso de `$count` em uma expressão `$filter`	GET `../users?$filter=assignedLicenses/$count eq 0&$count=true`
Usar de `$search`	GET `../applications?$search="displayName:Browser"`
Usar `$orderby` em propriedades selecionadas	GET `../applications?$orderby=displayName&$count=true`
Usar o `$filter` com o `endsWith` operador	GET `../users?$count=true&$filter=endsWith(mail,'@outlook.com')`
Usar o `$filter` e `$orderby` na mesma consulta	GET `../applications?$orderby=displayName&$filter=startsWith(displayName, 'Box')&$count=true`
Uso o `$filter` com os `startsWith` operadores em propriedades específicas.	GET `../users?$filter=startsWith(mobilePhone, '25478') OR startsWith(mobilePhone, '25473')&$count=true`
Usar o `$filter` com `ne` e `not` operadores
GET `../users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true`
Usar o `$filter` com `not` e `startsWith` operadores
GET `../users?$filter=NOT startsWith(displayName, 'Conf')&$count=true`
Uso de `$filter` em uma coleção com o operador `endsWith`	[GET](https://developer.microsoft.com/en-us/graph/graph-explorer?request=users%3F%24count%3Dtrue%26%24filter%3DproxyAddresses%2Fany(p%3AendsWith(p%2C%2B'OnMicrosoft.com'))%26select%3Did%2CdisplayName%2Cproxyaddresses&method=GET&version=beta& GraphUrl=https://graph.microsoft.com&headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d) `../users?$count=true&$filter=proxyAddresses/any(p:endsWith(p,+'OnMicrosoft.com'))&select=id,displayName,proxyaddresses`
Uso de conversão de OData com lista de membros transitivos	GET `../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 nas propriedades dos objetos do diretório Microsoft Azure Active Directory

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 que são suportadas por padrão também funcionarão em consultas avançadas, mas a resposta será eventualmente consistente.
O operador in é suportado por padrão sempre que o operador eq for suportado por padrão.
O operador endsWith é suportado apenas em consultas avançadas nas propriedades email, otherMails, userPrincipalName, e propriedades proxyAddresses.
Os operadores de negação not e ne são suportados apenas em consultas avançadas.
- Todas as propriedades que suportam o eq operador também suportam os ne ou not operadores.
- 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 suportados pelas funcionalidades de consulta avançada.

Legenda

O operador $filter funciona por padrão para essa propriedade.
O $filter operador exige parâmetros de consulta avançados, que são:
- ConsistencyLevel=eventual cabeçalho
- $count=true cadeia de caracteres
O operador $filter 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 aquela 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 forma alguma.

Propriedades da unidade administrativa

Nome da propriedade	eq	startsWith	ge	le	Valor nulo
descrição
displayName
isMemberManagementRestricted

Propriedades do aplicativo

Nome da propriedade	eq	startsWith	ge	le	Valor nulo
appId
createdDateTime
createdOnBehalfOf/deletedDateTime
createdOnBehalfOf/id
descrição
disabledByMicrosoftStatus
displayName
identifierUris/any(p:p)
info/logoUrl
info/termsOfServiceUrl
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)

Propriedades do dispositivo

Nome da propriedade	eq	startsWith	ge	le	Valor nulo
accountEnabled
alternativeSecurityIds/any(a:a/identityProvider)
alternativeSecurityIds/any(a:a/type)
approximateLastSignInDateTime
deviceId
displayName
extensionAttributes1-15
hostnames/any(p:p)
isCompliant
isManaged
mdmAppId
onPremisesLastSyncDateTime
onPremisesSyncEnabled
operatingSystem
operatingSystemVersion
physicalIds/any(p:p)
registrationDateTime

Propriedades do grupo

Nome da propriedade	eq	startsWith	ge	le	Valor nulo
assignedLicenses/any(a:a/skuId)
classificação
createdByAppId
createdOnBehalfOf/deletedDateTime
createdOnBehalfOf/id
descrição
displayName
expirationDateTime
hasMembersWithLicenseErrors
infoCatalogs/any(p:p)
isAssignableToRole
email
mailEnabled
mailNickname
membershipRule
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

Propriedades de contatos organizacionais

Nome da propriedade	eq	startsWith	ge	le	Valor 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

Propriedades da entidade de serviço

Nome da propriedade	eq	startsWith	ge	le	Valor nulo
accountEnabled
alternativeNames/any(p:p)
appId
appOwnerOrganizationId
appRoleAssignmentRequired
applicationTemplateId
createdObjects/any(c:c/id)
descrição
displayName
homepage
info/logoUrl
info/termsOfServiceUrl
preferredTokenSigningKeyEndDateTime
publisherName
servicePrincipalNames/any(p:p)
tags/any(p:p)

Propriedades de usuário

Nome da propriedade	eq	startsWith	ge	le	Valor nulo
accountEnabled
ageGroup
assignedLicenses/any(a:a/skuId)
assignedPlans/any(a:a/capabilityStatus)
assignedPlans/any(a:a/service)
assignedPlans/any(a:a/servicePlanId)
businessPhones/any(p:p)
cidade
CompanyName
consentProvidedForMinor
country
createdDateTime
createdObjects/any(c:c/id)
creationType
departamento
displayName
employeeHireDate
employeeId
employeeOrgData/costCenter
employeeOrgData/division
employeeType
externalUserState
faxNumber
givenName
identities/any(i:i/issuer)
imAddresses/any(p:p)
infoCatalogs/any(p:p)
isResourceAccount
jobTitle
email
mailNickname
manager/deletedDateTime
manager/id
mobilePhone
officeLocation
onPremisesExtensionAttributes/extensionAttribute1-15
onPremisesImmutableId
onPremisesLastSyncDateTime
onPremisesProvisioningErrors/any(o:o/category)
onPremisesProvisioningErrors/any(o:o/propertyCausingError)
onPremisesSamAccountName
onPremisesSecurityIdentifier
onPremisesSyncEnabled
onPremisesUserPrincipalName
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)
showInAddressList
state
streetAddress
sobrenome
usageLocation
userPrincipalName
userType

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çadas. 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 for usado.

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

{
    "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 retorna um erro.

https://graph.microsoft.com/v1.0/applications?$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.

https://graph.microsoft.com/v1.0/users?$filter=endsWith(mail,'@outlook.com')

{
    "error": {
        "code": "Request_UnsupportedQuery",
        "message": "Unsupported Query.",
        "innerError": {
            "date": "2021-05-18T19:12:36",
            "request-id": "63f2093c-399c-4350-9609-3ce9b62abe3c",
            "client-request-id": "e60ed0ba-df5d-e190-f056-f9c0318456d7"
        }
    }
}

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, a solicitação retorna um erro.

https://graph.microsoft.com/beta/groups?$filter=createdDateTime ge 2021-11-01&$count=true
ConsistencyLevel: eventual

{
    "error": {
        "code": "Request_UnsupportedQuery",
        "message": "The request uses a filter property that is not indexed",
        "innerError": {
            "date": "2021-06-10T19:32:01",
            "request-id": "5625ba13-0c9f-4fce-a853-4b52f3e0bd09",
            "client-request-id": "76fe4cd8-df3a-f8c3-659b-594274b6bb31"
        }
    }
}

No entanto, é importante observar que os parâmetros de consulta especificados em uma solicitação podem falhar silenciosamente. Isso pode ser verdadeiro para parâmetros de consulta sem suporte, bem como para combinações de parâmetros de consulta sem suporte. Nesses casos, você deve examinar os dados retornados pela solicitação para determinar se os parâmetros de consulta que especificou tiveram o efeito desejado. Por exemplo, no exemplo a seguir, falta o parâmetro @odata.count mesmo que a consulta seja bem sucedida.

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

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