Funcionalidades avanzadas de consulta en objetos Microsoft Entra ID
Microsoft Graph admite funcionalidades avanzadas de consulta en varios objetos de Microsoft Entra ID, también denominados objetos de directorio, para ayudarle a acceder de forma eficaz a los datos. Por ejemplo, la adición de los operadores No (not
), No es igual (ne
) y Termina con (endsWith
) en el parámetro de consulta $filter
.
El motor de consulta de Microsoft Graph usa un almacén de índices para satisfacer las solicitudes de consulta. Para agregar compatibilidad con funcionalidades de consulta adicionales en algunas propiedades, es posible que esas propiedades se indexen en un almacén independiente. Esta indexación independiente mejora el rendimiento de las consultas. Sin embargo, estas funcionalidades avanzadas de consulta no están disponibles de forma predeterminada, pero el solicitante debe establecer el encabezado eventual
ConsistencyLevel en y, excepto en $search
, usar el parámetro de $count
consulta. El encabezado ConsistencyLevel y $count
se denominan parámetros de consulta avanzada.
Por ejemplo, si desea recuperar solo las cuentas de usuario inactivas, puede ejecutar cualquiera de estas consultas que usan el parámetro de consulta $filter
.
Opción 1: Use el parámetro de $filter
consulta con el eq
operador . Esta solicitud funciona de forma predeterminada y no requiere los parámetros de consulta avanzados.
GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled eq false
Opción 2: Use el parámetro de $filter
consulta con el ne
operador . Esta solicitud no se admite de forma predeterminada porque el ne
operador solo se admite en consultas avanzadas. Por lo tanto, debe agregar el encabezado ConsistencyLevel establecido en eventual
y usar la cadena de $count=true
consulta.
GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled ne true&$count=true
ConsistencyLevel: eventual
Microsoft Entra ID objetos (directorio) que admiten funcionalidades avanzadas de consulta
Las funcionalidades avanzadas de consulta solo se admiten en objetos de directorio y sus relaciones, incluidos los siguientes objetos:
Escenarios de consulta que requieren funcionalidades avanzadas de consulta
La siguiente tabla enumera los escenarios de consulta de los objetos del directorio que solo se admiten en las consultas avanzadas:
Descripción | Ejemplo |
---|---|
Uso de $count como segmento de dirección URL |
GET~/groups/$count |
Uso de $count como parámetro de cadena de consulta |
GET~/servicePrincipals?$count=true |
Uso de $count en una expresión $filter |
GET~/users?$filter=assignedLicenses/$count eq 0&$count=true |
Uso de $search |
GET~/applications?$search="displayName:Browser" |
Uso de $orderby en propiedades de selección |
GET~/applications?$orderby=displayName&$count=true |
Uso de $filter con el operador endsWith |
GET~/users?$count=true&$filter=endsWith(mail,'@outlook.com') |
Uso de $filter y $orderby en la misma consulta |
GET../applications?$orderby=displayName&$filter=startsWith(displayName, 'Box')&$count=true |
Uso de $filter con los operadores startsWith en propiedades específicas. |
GET~/users?$filter=startsWith(mobilePhone, '25478') OR startsWith(mobilePhone, '25473')&$count=true |
Uso de $filter con operadores ne y not |
GET~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true |
Uso de $filter con operadores not y startsWith |
GET~/users?$filter=NOT startsWith(displayName, 'Conf')&$count=true |
Uso de $filter en una colección con el operador endsWith |
GET~/users?$count=true&$filter=proxyAddresses/any (p:endsWith(p, 'contoso.com'))&$select=id,displayName,proxyaddresses |
Uso de la conversión de OData con la lista de miembros transitivos |
GET~/me/transitiveMemberOf/microsoft.graph.group?$count=true |
Nota:
- Solo se admite usar
$filter
y$orderby
juntos con consultas avanzadas. -
$expand
no se admite actualmente con consultas avanzadas. - Las funcionalidades de consulta avanzadas no están disponibles actualmente para los inquilinos de Azure AD B2C.
- Para usar funcionalidades de consulta avanzadas en solicitudes por lotes, especifica el encabezado ConsistencyLevel en el cuerpo JSON de la solicitud de
POST
.
Compatibilidad con el filtrado por propiedades de objetos de Microsoft Entra ID (directorio)
Las propiedades de los objetos de directorio se comportan de forma diferente en cuanto a su compatibilidad con los parámetros de consulta. Los siguientes son escenarios comunes para los objetos del directorio:
- El operador
in
se admite de forma predeterminada donde se admita el operadoreq
de forma predeterminada. - El
endswith
operador solo se admite con parámetros de consulta avanzados y solo por correo, otras propiedadesMails, userPrincipalName y proxyAddresses . - La obtención de colecciones vacías (
/$count eq 0
,/$count ne 0
) y colecciones con menos de un objeto (/$count eq 1
,/$count ne 1
) solo se admite con parámetros de consulta avanzados. - Los
not
operadores de negación yne
solo se admiten con parámetros de consulta avanzados.- Todas las propiedades que admiten el
eq
operador también admiten losne
operadores onot
. - Para las consultas que usan el operador lambda
any
, use el operadornot
. Vea Filtrar mediante operadores lambda.
- Todas las propiedades que admiten el
En las tablas siguientes se resume la compatibilidad con $filter
operadores por propiedades de objetos de directorio e indica dónde se admite la consulta a través de funcionalidades de consulta avanzadas.
Leyenda
-
El
$filter
operador funciona de forma predeterminada para esa propiedad. -
El
$filter
operador solo funciona sin parámetros de consulta avanzados. -
El
$filter
operador requiereparámetros de consulta avanzados, que son:- Encabezado
ConsistencyLevel=eventual
- Cadena de consulta
$count=true
- Encabezado
-
El
$filter
operador no se admite en esa propiedad. Envíenos comentarios para solicitar que esta propiedad sea compatible con$filter
para sus escenarios. - Las celdas en blanco indican que la consulta no es válida para esa propiedad.
- La columna valor NULL indica que la propiedad admite valores NULL y se puede filtrar mediante
null
. - Las propiedades que no aparecen aquí no admiten
$filter
en absoluto.
Propiedades de unidad administrativa
Propiedad | eq | startsWith | eq Null |
---|---|---|---|
description |
|
|
|
displayName |
|
|
|
isMemberManagementRestricted |
|
||
membershipRule |
|
|
|
membershipRuleProcessingState |
|
Propiedades de la aplicación
Propiedad | eq | startsWith | ge/le | eq Null |
---|---|---|---|---|
appId |
|
|||
createdDateTime |
|
|
||
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 |
|
|
||
notas |
|
|
|
|
publicClient/redirectUris/any(p:p) |
|
|
||
publisherDomain |
|
|
||
requiredResourceAccess/any(r:r/resourceAppId) |
|
|||
serviceManagementReference |
|
|
|
|
signInAudience |
|
|||
spa/redirectUris/any(p:p) |
|
|
||
tags/any(p:p) |
|
|
||
uniqueName |
|
|
||
verifiedPublisher/displayName |
|
|
|
|
web/homePageUrl |
|
|
|
|
web/redirectUris/any(p:p) |
|
|
Las siguientes propiedades de la entidad de aplicación admiten $count
una colección en una expresión de filtro.
Propiedad | eq Count 0 | eq Count 1 |
---|---|---|
extensionProperties/$count |
|
|
federatedIdentityCredentials/$count |
|
|
Propiedades del contrato
Propiedad | eq | startsWith |
---|---|---|
customerId |
|
|
defaultDomainName |
|
|
displayName |
|
|
Propiedades de dispositivo
Propiedad | 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 |
|
|
||
manufacturer |
|
|
|
|
mdmAppId |
|
|
||
model |
|
|
|
|
onPremisesLastSyncDateTime |
|
|||
onPremisesSecurityIdentifier |
|
|
||
onPremisesSyncEnabled |
|
|
||
operatingSystem |
|
|
|
|
operatingSystemVersion |
|
|
|
|
physicalIds/any(p:p) |
|
|||
profileType |
|
|||
registrationDateTime |
|
|
||
trustType |
|
Las siguientes propiedades de la compatibilidad de la entidad $count
de dispositivo de una colección en una expresión de filtro.
Propiedad | eq Count 0 | eq Count 1 |
---|---|---|
physicalIds/$count |
|
|
systemLabels/$count |
|
|
Propiedades del rol de directorio
Propiedad | eq | startsWith | eq Null |
---|---|---|---|
description |
|
|
|
displayName |
|
|
|
roleTemplateId |
|
|
Propiedades de grupo
Propiedad | eq | startsWith | ge/le | eq Null |
---|---|---|---|---|
assignedLicenses/any(a:a/skuId) |
|
|||
classification |
|
|
||
createdByAppId |
|
|||
createdDateTime |
|
|
||
description |
|
|
|
|
displayName |
|
|
|
|
expirationDateTime |
|
|||
groupTypes/any(p:p) |
|
|||
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 |
|
|||
uniqueName |
|
|
Las siguientes propiedades de la compatibilidad de entidades $count
de grupo de una colección en una expresión de filtro.
Propiedad | eq Count 0 | eq Count 1 |
---|---|---|
assignedLicenses/$count |
|
|
onPremisesProvisioningErrors/$count |
|
|
proxyAddresses/$count |
|
|
Propiedades de contacto de la organización
Propiedad | 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 |
|
|
|
Las siguientes propiedades de la entidad orgContact admiten $count
una colección en una expresión de filtro.
Propiedad | eq Count 0 | eq Count 1 |
---|---|---|
onPremisesProvisioningErrors/$count |
|
|
proxyAddresses/$count |
|
|
Propiedades de la entidad de servicio
Propiedad | eq | startsWith | ge/le | eq Null |
---|---|---|---|---|
accountEnabled |
|
|||
alternativeNames/any(p:p) |
|
|
||
appId |
|
|||
appOwnerOrganizationId |
|
|||
appRoleAssignmentRequired |
|
|||
applicationTemplateId |
|
|||
claimsPolicy/id |
|
|||
createdObjects/any(c:c/id) |
|
|||
description |
|
|
|
|
displayName |
|
|
|
|
federatedIdentityCredentials/any(f:f/issuer) |
|
|
||
federatedIdentityCredentials/any(f:f/name) |
|
|
||
federatedIdentityCredentials/any(f:f/subject) |
|
|
||
homepage |
|
|
|
|
info/logoUrl |
|
|||
info/termsOfServiceUrl |
|
|
||
notas |
|
|
|
|
preferredSingleSignOnMode |
|
|||
preferredTokenSigningKeyEndDateTime |
|
|||
publisherName |
|
|
||
remoteDesktopSecurityConfiguration/id |
|
|||
servicePrincipalNames/any(p:p) |
|
|
||
servicePrincipalType |
|
|||
tags/any(p:p) |
|
|
||
verifiedPublisher/displayName |
|
|
|
Las siguientes propiedades de la entidad servicePrincipal admiten $count
una colección en una expresión de filtro.
Propiedad | eq Count 0 | eq Count 1 |
---|---|---|
federatedIdentityCredentials/$count |
|
|
Propiedades de usuarios
Propiedad | eq | startsWith | ge/le | eq Null |
---|---|---|---|---|
accountEnabled |
|
|||
ageGroup |
|
|||
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 |
|
|
|
|
|
|
|
||
mailNickname |
|
|
|
|
mobilePhone |
|
|
|
|
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) |
|
|
||
state |
|
|
||
streetAddress |
|
|
|
|
surname |
|
|
|
|
usageLocation |
|
|
|
|
userPrincipalName |
|
|
||
userType |
|
|
Las siguientes propiedades de la compatibilidad de la entidad $count
de usuario de una colección en una expresión de filtro.
Propiedad | eq Count 0 | eq Count 1 |
---|---|---|
assignedLicenses/$count |
|
|
onPremisesProvisioningErrors/$count |
|
|
otherMails/$count |
|
|
ownedObjects/$count |
|
|
proxyAddresses/$count |
|
|
En la tabla siguiente se muestra la compatibilidad con $filter
otras propiedades de extensión en el objeto de usuario .
Tipo de extensión | eq | startsWith | eq null |
---|---|---|---|
Extensiones de esquema |
|
|
|
Extensiones abiertas |
|
|
|
Extensiones de directorio |
|
|
|
Compatibilidad con la ordenación por propiedades de objetos de Microsoft Entra ID (directorio)
En la tabla siguiente se resume la compatibilidad con $orderby
las propiedades de los objetos de directorio e indica dónde se admite la ordenación mediante funcionalidades de consulta avanzadas.
Leyenda
-
El
$orderby
operador funciona de forma predeterminada para esa propiedad. -
El
$orderby
operador requiereparámetros de consulta avanzados, que son:- Encabezado
ConsistencyLevel=eventual
- Cadena de consulta
$count=true
- Encabezado
- El uso de
$filter
y$orderby
en la misma consulta para objetos de directorio siempre requiere parámetros de consulta avanzados. Para obtener más información, consulte Escenarios de consulta que requieren funcionalidades avanzadas de consulta.
Objeto de directorio | Nombre de propiedad | $orderby |
---|---|---|
administrativeUnit | createdDateTime |
|
administrativeUnit | deletedDateTime |
|
administrativeUnit | displayName |
|
aplicación | createdDateTime |
|
aplicación | deletedDateTime |
|
aplicación | displayName |
|
orgContact | createdDateTime |
|
orgContact | displayName |
|
dispositivo | approximateLastSignInDateTime |
|
dispositivo | createdDateTime |
|
dispositivo | deletedDateTime |
|
dispositivo | displayName |
|
grupo | createdDateTime |
|
grupo | deletedDateTime |
|
grupo | displayName |
|
servicePrincipal | createdDateTime |
|
servicePrincipal | deletedDateTime |
|
servicePrincipal | displayName |
|
usuario | createdDateTime |
|
usuario | deletedDateTime |
|
usuario | displayName |
|
usuario | userPrincipalName |
|
[todos los demás] | [todos los demás] |
|
Control de errores para consultas avanzadas en objetos de directorio
En la sección siguiente se proporcionan ejemplos de escenarios de error comunes cuando no se usan parámetros de consulta avanzados cuando es necesario.
El recuento de objetos de directorio solo se admite mediante los parámetros de consultas avanzadas. Si no se especifica el ConsistencyLevel=eventual
encabezado, la solicitud devuelve un error cuando se usa el $count
segmento de dirección URL (/$count
) o omite de forma silenciosa el $count
parámetro de consulta (?$count=true
) si se usa.
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"
}
}
}
En el caso de los objetos de directorio, $search
solo funciona en consultas avanzadas. Si no se especifica el encabezado ConsistencyLevel , la solicitud devuelve un error.
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"
}
}
}
Si una propiedad o un parámetro de consulta en la URL solo se admite en las consultas avanzadas pero falta el encabezado ConsistencyLevel o la cadena de consulta $count=true
, la solicitud devuelve un error.
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"
}
}
}
Si una propiedad no se indexa para admitir un parámetro de consulta, la solicitud devuelve un error incluso si se especifican parámetros de consulta avanzados. Por ejemplo, la propiedad createdDateTime del recurso de grupo no se indexa para las funcionalidades de consulta.
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"
}
}
}
Sin embargo, una solicitud que incluya parámetros de consulta podría producir un error silencioso. Por ejemplo, para parámetros de consulta no admitidos y para combinaciones no admitidas de parámetros de consulta. En estos casos, examine los datos devueltos por la solicitud para determinar si los parámetros de consulta especificados tuvieron el efecto deseado. Por ejemplo, el parámetro @odata.count
falta aunque la consulta sea exitosa.
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"
}
]
}