Este método admite los $countparámetros de consulta , $expand, $filter, $orderby$search, $selecty $top OData para ayudar a personalizar la respuesta. No se admite $skip. Debe especificar o $filter=signInActivity al enumerar$select=signInActivity usuarios, ya que la propiedad signInActivity no se devuelve de forma predeterminada.
Algunas consultas solo se admiten cuando se usa el encabezado ConsistencyLevel establecido en eventual y $count. Para obtener más información, vea Funcionalidades avanzadas de consulta en objetos de directorio. Los parámetros $count y $search no están disponibles actualmente en espacios empresariales de Azure AD B2C.
De forma predeterminada, solo se devuelve un conjunto limitado de propiedades (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname y userPrincipalName). Para devolver un conjunto de propiedades alternativo, especifique el conjunto deseado de propiedades del usuario mediante el parámetro de consulta OData $select. Por ejemplo, para devolver displayName, givenName y postalCode, agregue lo siguiente a su consulta $select=displayName,givenName,postalCode.
Las propiedades de extensión también admiten parámetros de consulta como se indica a continuación:
Tipo de extensión
Comentarios
onPremisesExtensionAttributes 1-15
Solo se devuelve con $select. Admite $filter (eq, ne y eq en valores null).
Extensiones de esquema
Solo se devuelve con $select. Admite $filter (eq, ne y eq en valores null).
Extensiones abiertas
Solo se devuelve con $expand, es decir, users?$expand=extensions.
Extensiones de directorio
Solo se devuelve con $select. Admite $filter (eq, ne y eq en valores null).
Algunas propiedades no se pueden devolver dentro de una colección de usuarios. Las siguientes propiedades solo se admiten al recuperar un único usuario: aboutMe, birthday, hireDate, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills, mailboxSettings.
Las siguientes propiedades no se admiten en cuentas personales de Microsoft y serán null: aboutMe, birthday, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills, streetAddress.
No proporcione un cuerpo de solicitud para este método.
Respuesta
Si se ejecuta correctamente, este método devuelve un código de respuesta 200 OK y la colección de objetos user en el cuerpo de la respuesta. Si se devuelve una colección de usuarios grande, puede usar la paginación en la aplicación.
Al intentar usar $select en la /users colección para recuperar propiedades que no se pueden devolver dentro de una colección de usuarios (por ejemplo, la solicitud ../users?$select=aboutMe), se devuelve un 501 Not Implemented código de error.
// 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();
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get();
Ejemplo 2: obtener una cuenta de usuario con un nombre de inicio de sesión
Solicitud
En el ejemplo siguiente se muestra la solicitud.
Nota: al filtrar por issuerAssignedId, debe proporcionar tanto el emisor como el issuerAssignedId. Sin embargo, el valor del emisor se omitirá en determinados escenarios. Para obtener más información sobre el filtrado de identidades, consulte objectIdentity resource type (Tipo de recurso objectIdentity).
GET https://graph.microsoft.com/v1.0/users?$select=displayName,id&$filter=identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')
// 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.Select = new string []{ "displayName","id" };
requestConfiguration.QueryParameters.Filter = "identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')";
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')" --select "displayName,id"
// 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.select = new String []{"displayName", "id"};
requestConfiguration.queryParameters.filter = "identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')";
});
En el ejemplo siguiente se muestra la solicitud. Esta solicitud requiere el encabezado ConsistencyLevel establecido en eventual porque $count está en la solicitud. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.
Nota: Los parámetros de consulta $count y $search actualmente no están disponibles en inquilinos de Azure AD B2C.
GET https://graph.microsoft.com/v1.0/users/$count
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
await graphClient.Users.Count.GetAsync((requestConfiguration) =>
{
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
graphClient.users().count().get(requestConfiguration -> {
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
Ejemplo 4: Usar $filter y $top para obtener un usuario con un nombre para mostrar que comience por "a", junto con un recuento de los objetos devueltos
Solicitud
En el ejemplo siguiente se muestra la solicitud. Esta solicitud requiere el encabezado ConsistencyLevel establecido en eventual y la cadena de consulta $count=true porque la solicitud tiene los parámetros de consulta $orderby y $filter. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.
Nota: Los parámetros de consulta $count y $search actualmente no están disponibles en inquilinos de Azure AD B2C.
GET https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName,'a')&$orderby=displayName&$count=true&$top=1
ConsistencyLevel: eventual
Respuesta
En el ejemplo siguiente se muestra la respuesta.
Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.
Ejemplo 5: Use $filter para obtener todos los usuarios con un correo que termine con ""a@contoso.com, incluido un recuento de objetos devueltos, con los resultados ordenados por userPrincipalName.
Solicitud
En el ejemplo siguiente se muestra la solicitud. Esta solicitud requiere el encabezado ConsistencyLevel establecido en eventual y la cadena de consulta $count=true porque la solicitud tiene los parámetros de consulta $orderby y $filter, y también usa el operador endsWith. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.
Nota: Los parámetros de consulta $count y $search actualmente no están disponibles en inquilinos de Azure AD B2C.
GET https://graph.microsoft.com/v1.0/users?$filter=endswith(mail,'a@contoso.com')&$orderby=userPrincipalName&$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 = "endswith(mail,'a@contoso.com')";
requestConfiguration.QueryParameters.Orderby = new string []{ "userPrincipalName" };
requestConfiguration.QueryParameters.Count = true;
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "endswith(mail,'a@contoso.com')" --count "true" --orderby "userPrincipalName" --consistency-level "eventual"
// 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(mail,'a@contoso.com')";
requestConfiguration.queryParameters.orderby = new String []{"userPrincipalName"};
requestConfiguration.queryParameters.count = true;
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
Ejemplo 6: use $search para obtener usuarios cuyos nombres para mostrar contengan las letras "wa", junto con un recuento de los objetos devueltos
Solicitud
En el ejemplo siguiente se muestra la solicitud. Esta solicitud requiere el encabezado ConsistencyLevel establecido en eventual porque $search está en la solicitud. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.
Nota: Los parámetros de consulta $count y $search actualmente no están disponibles en inquilinos de Azure AD B2C.
GET https://graph.microsoft.com/v1.0/users?$search="displayName:wa"&$orderby=displayName&$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.Search = "\"displayName:wa\"";
requestConfiguration.QueryParameters.Orderby = new string []{ "displayName" };
requestConfiguration.QueryParameters.Count = true;
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --search ""displayName:wa"" --count "true" --orderby "displayName" --consistency-level "eventual"
// 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.search = "\"displayName:wa\"";
requestConfiguration.queryParameters.orderby = new String []{"displayName"};
requestConfiguration.queryParameters.count = true;
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
Ejemplo 7: use $search para obtener usuarios con nombres para mostrar que contengan las letras "wa" o las letras "to", junto con un recuento de los objetos devueltos
Solicitud
En el ejemplo siguiente se muestra la solicitud. Esta solicitud requiere el encabezado ConsistencyLevel establecido en eventual porque $search está en la solicitud. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.
Nota: Los parámetros de consulta $count y $search actualmente no están disponibles en inquilinos de Azure AD B2C.
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --search ""displayName:wa" OR "displayName:ad"" --count "true" --consistency-level "eventual"
Ejemplo 8: Obtención de usuarios invitados (B2B) de un inquilino o dominio específicos por userPrincipalName
Solicitud
En el ejemplo siguiente se muestra la solicitud. El valor userPrincipalName para los usuarios invitados (colaboración B2B) siempre contiene el identificador "#EXT#". Por ejemplo, userPrincipalName de un usuario en su inquilino principal es AdeleV@adatum.com. Al invitar al usuario a colaborar en el inquilino, contoso.com, su userPrincipalName en el inquilino es "AdeleV_adatum.com#EXT#@contoso.com".
Esta solicitud requiere el encabezado ConsistencyLevel establecido en eventual y la cadena de $count=true consulta porque la solicitud incluye el operador endsWith. Para obtener más información sobre el uso de ConsistencyLevel y $count, vea Funcionalidades avanzadas de consulta en objetos de directorio.
NOTA: Debe codificar el carácter reservado "#" en el valor userPrincipalName como "%23" en la dirección URL de la solicitud. Para obtener más información, vea Codificación de caracteres especiales.
GET https://graph.microsoft.com/v1.0/users?$select=id,displayName,mail,identities&$filter=endsWith(userPrincipalName,'%23EXT%23@contoso.com')&$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.Select = new string []{ "id","displayName","mail","identities" };
requestConfiguration.QueryParameters.Filter = "endsWith(userPrincipalName,'";
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "endsWith(userPrincipalName,'" --select "id,displayName,mail,identities" --consistency-level "eventual"
// 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.select = new String []{"id", "displayName", "mail", "identities"};
requestConfiguration.queryParameters.filter = "endsWith(userPrincipalName,'";
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
Ejemplo 9: Uso de $filter para obtener usuarios a los que se les asigna una licencia específica
Solicitud
En el ejemplo siguiente se muestra la solicitud.
GET https://graph.microsoft.com/v1.0/users?$select=id,mail,assignedLicenses&$filter=assignedLicenses/any(u:u/skuId eq cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46)
GET https://graph.microsoft.com/v1.0/users?$select=ext55gb1l09_msLearnCourses
// 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.Select = new string []{ "ext55gb1l09_msLearnCourses" };
});
// 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.select = new String []{"ext55gb1l09_msLearnCourses"};
});
En la respuesta siguiente, la propiedad de extensión de esquema ext55gb1l09_msLearnCourses no está asignada en dos de los objetos de usuario.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(ext55gb1l09_msLearnCourses)",
"value": [
{},
{
"ext55gb1l09_msLearnCourses": {
"@odata.type": "#microsoft.graph.ComplexExtensionValue",
"courseType": "Developer",
"courseName": "Introduction to Microsoft Graph",
"courseId": 1
}
},
{}
]
}
Nota: También puede aplicar $filter en la propiedad de extensión de esquema para recuperar objetos en los que una propiedad de la colección coincida con un valor especificado. La sintaxis es /users?$filter={schemaPropertyID}/{propertyName} eq 'value'. Por ejemplo, GET /users?$select=ext55gb1l09_msLearnCourses&$filter=ext55gb1l09_msLearnCourses/courseType eq 'Developer'. Se admiten los operadores eq y not.
Ejemplo 11: Obtención de usuarios que incluyan su última hora de inicio de sesión
Solicitud
En el ejemplo siguiente se muestra la solicitud. Los detalles de la propiedad signInActivity requieren una licencia Microsoft Entra ID P1 o P2 y el permiso AuditLog.Read.All.
Nota: Al especificar $select=signInActivity o $filter=signInActivity al enumerar usuarios, el tamaño máximo de página para $top es 120. Las solicitudes con $top un conjunto superior a 120 devolverán páginas con hasta 120 usuarios. signInActivity admite $filter (eq, ne, not, ge, le), pero no con ninguna otra propiedad filtrable.
GET https://graph.microsoft.com/v1.0/users?$select=displayName,userPrincipalName,signInActivity
// 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.Select = new string []{ "displayName","userPrincipalName","signInActivity" };
});
// 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.select = new String []{"displayName", "userPrincipalName", "signInActivity"};
});
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.