Funcionalidades avanzadas de consulta en objetos Microsoft Entra ID

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.

HTTP

GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled eq false

C#

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

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "accountEnabled eq false"

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Ir

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)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Java

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

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('accountEnabled eq false')
	.get();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PHP

<?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();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PowerShell

Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "accountEnabled eq false" 

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Python

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)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

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.

HTTP

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

C#

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

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "accountEnabled ne true" --count "true" --consistency-level "eventual"

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Ir

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)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Java

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

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.header('ConsistencyLevel','eventual')
	.filter('accountEnabled ne true')
	.get();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PHP

<?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();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PowerShell

Import-Module Microsoft.Graph.Users

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

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Python

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)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

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.

Legend

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

Legend

• 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	Admite $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

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.

HTTP

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

C#

// 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();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users count get

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Ir

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



graphClient.Users().Count().Get(context.Background(), nil)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

graphClient.users().count().get();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let int32 = await client.api('/users/$count')
	.get();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$graphServiceClient->users()->count()->get()->wait();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PowerShell

Import-Module Microsoft.Graph.Users

Get-MgUserCount

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Python

from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


await graph_client.users.count.get()

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

{
    "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.

HTTP

GET https://graph.microsoft.com/v1.0/applications?$search="displayName:Browser"

C#

// 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\"";
});

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc applications list --search ""displayName:Browser""

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Ir

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)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Java

// 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\"";
});

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let applications = await client.api('/applications')
	.search('displayName:Browser')
	.get();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PHP

<?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();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PowerShell

Import-Module Microsoft.Graph.Applications

Get-MgApplication -Search '"displayName:Browser"' 

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Python

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)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

{
    "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.

HTTP

GET https://graph.microsoft.com/beta/users?$filter=endsWith(userPrincipalName,'%23EXT%23@contoso.com')

C#

// 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,'";
});

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta users list --filter "endsWith(userPrincipalName,'"

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Ir

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)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Java

// 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,'";
});

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

JavaScript

Snippet not available

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PHP

<?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();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PowerShell

Import-Module Microsoft.Graph.Beta.Users

Get-MgBetaUser -Filter "endsWith(userPrincipalName,'" 

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Python

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)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

{
    "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.

HTTP

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

C#

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

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta groups list --filter "createdDateTime ge 2021-11-01" --count "true" --consistency-level "eventual"

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Ir

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)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Java

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

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

JavaScript

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();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PHP

<?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();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PowerShell

Import-Module Microsoft.Graph.Beta.Groups

Get-MgBetaGroup -Filter "createdDateTime ge 2021-11-01" -CountVariable CountVar  -ConsistencyLevel eventual 

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Python

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)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

{
    "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.

HTTP

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

C#

// 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;
});

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --count "true"

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Ir

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)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Java

// 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;
});

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.get();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PHP

<?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();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PowerShell

Import-Module Microsoft.Graph.Users

Get-MgUser -CountVariable CountVar 

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Python

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)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

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

Contenido relacionado

• Usar parámetros de consulta para personalizar respuestas
• Limitaciones del parámetro de consulta
• Usar el parámetro de consulta $search para que coincida con un criterio de búsqueda
• Exploración de funcionalidades avanzadas de consulta para objetos Microsoft Entra ID con el SDK de .NET