Recursos avançados de consulta em objetos Microsoft Entra ID
À 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 eventual
e, 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
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 eventual
ConsistencyLevele 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
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:
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 operadoreq
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 ene
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 aosne
operadores ounot
. - Para consultas que utilizam o
any
operador lambda, usar onot
operador. Veja Filtrar utilizando operadores lambda.
- Todas as propriedades que dão suporte ao
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.
Legend
- 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 | ||||
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 | ||||
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) | ||||
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.
Legend
- 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 | Dá suporte a $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 |
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
{
"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"
{
"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')
{
"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
{
"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
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"
}
]
}
Conteúdo relacionado
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de