Funcionalidades avanzadas de consulta en objetos Microsoft Entra ID

Artículo
04/16/2024

A medida que Microsoft Entra sigue ofreciendo más funcionalidades y mejoras en estabilidad, disponibilidad y rendimiento, Microsoft Graph también continúa evolucionando y escalando para acceder de forma eficaz a los datos. Una forma es la compatibilidad creciente de Microsoft Graph con funcionalidades avanzadas de consulta en varios objetos Microsoft Entra ID, también denominados objetos de directorio y sus propiedades. 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 soporte con funcionalidades de consulta adicionales en algunas propiedades, estas propiedades se indexan ahora en un almacén independiente. Esta indexación independiente permite Microsoft Entra ID aumentar la compatibilidad y mejorar el rendimiento de las solicitudes de consulta. Sin embargo, estas funcionalidades avanzadas de consulta no están disponibles de forma predeterminada, pero el solicitante también debe establecer el encabezado eventualConsistencyLevel 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, es decir, la solicitud no requiere los parámetros de consulta avanzados.

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)

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 eventualy usar la cadena de $count=true 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 (directorio) que admiten funcionalidades avanzadas de consulta

Estas funcionalidades avanzadas de consulta solo se admiten en objetos de directorio y sus relaciones, incluidos los siguientes objetos usados con frecuencia:

Objeto	Relaciones
administrativeUnit	members
application	owners
appRoleAssignment	-
dispositivo	memberOf transitiveMemberOf registeredUsers registeredOwners
group	members transitiveMembers memberOf transitiveMemberOf owners appRoleAssignments
oAuth2PermissionGrant (concesiones de permisos delegados)	-
orgContact	memberOf transitiveMemberOf
servicePrincipal	memberOf transitiveMemberOf appRoleAssignments appRoleAssignmentsTo oAuth2PermissionGrant
user	memberOf transitiveMemberOf ownedObjects registeredDevices ownedDevices transitiveManagers directReports transitiveReports appRoleAssignments oAuth2PermissionGrant

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:

Las consultas admitidas de forma predeterminada también funcionarán con parámetros de consulta avanzados, pero la respuesta será finalmente coherente.
El operador in se admite de forma predeterminada donde se admita el operador eq de forma predeterminada.
El endsWith operador solo se admite con parámetros de consulta avanzados 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 y ne solo se admiten con parámetros de consulta avanzados.
- Todas las propiedades que admiten el eq operador también admiten los ne operadores o not .
- Para las consultas que usan el operador lambda any, use el operador not. Vea Filtrar mediante operadores lambda.

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 requiereparámetros de consulta avanzados, que son:
- Encabezado ConsistencyLevel=eventual
- Cadena de consulta $count=true
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
scopedRoleMembers/any(s:s/id)

Propiedades de la aplicación

Propiedad	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
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
appRoleAssignments/any(a:a/id)
assignedLicenses/any(a:a/skuId)
classification
createdByAppId
createdOnBehalfOf/id
description
displayName
expirationDateTime
hasMembersWithLicenseErrors
infoCatalogs/any(p:p)
isAssignableToRole
mail
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
settings/any(s:s/displayName)
settings/any(s:s/id)
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
mail
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
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
notas
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

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
ownedObjects/$count

Propiedades de usuarios

Propiedad	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)
mail
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

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

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 o omite silenciosamente el $count parámetro de consulta (?$count=true) si se usa.

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

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"


// 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"
        }
    }
}

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')


// 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"
        }
    }
}

Si una propiedad no se ha indexado para admitir un parámetro de consulta, incluso si se especifican los parámetros de consulta avanzados, la solicitud devuelve un error.

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

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


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

Funcionalidades avanzadas de consulta en objetos Microsoft Entra ID

Microsoft Entra ID objetos (directorio) que admiten funcionalidades avanzadas de consulta

Escenarios de consulta que requieren funcionalidades avanzadas de consulta

Compatibilidad con el filtrado por propiedades de objetos de Microsoft Entra ID (directorio)

Leyenda

Propiedades de unidad administrativa

Propiedades de la aplicación

Propiedades del contrato

Propiedades de dispositivo

Propiedades del rol de directorio

Propiedades de grupo

Propiedades de contacto de la organización

Propiedades de la entidad de servicio

Propiedades de usuarios

Compatibilidad con la ordenación por propiedades de objetos de Microsoft Entra ID (directorio)

Leyenda

Control de errores para consultas avanzadas en objetos de directorio

Comentarios

Comentarios

Recursos adicionales

Funcionalidades avanzadas de consulta en objetos Microsoft Entra ID

Microsoft Entra ID objetos (directorio) que admiten funcionalidades avanzadas de consulta

Escenarios de consulta que requieren funcionalidades avanzadas de consulta

Compatibilidad con el filtrado por propiedades de objetos de Microsoft Entra ID (directorio)

Leyenda

Propiedades de unidad administrativa

Propiedades de la aplicación

Propiedades del contrato

Propiedades de dispositivo

Propiedades del rol de directorio

Propiedades de grupo

Propiedades de contacto de la organización

Propiedades de la entidad de servicio

Propiedades de usuarios

Compatibilidad con la ordenación por propiedades de objetos de Microsoft Entra ID (directorio)

Leyenda

Control de errores para consultas avanzadas en objetos de directorio

Contenido relacionado

Comentarios

Comentarios

Recursos adicionales