Esse método dá suporte aos $countparâmetros de consulta , $expand, $filter, $orderby, $search, $selecte $topOData para ajudar a personalizar a resposta. $skip não é compatível. Você deve especificar $select=signInActivity ou $filter=signInActivity , ao listar usuários, pois a propriedade signInActivity não é retornada por padrão.
Algumas consultas são suportadas somente quando se usa o cabeçalho ConsistencyLevel definido como eventual e $count. Para obter mais informações, consulte Recursos avançados de consulta em objetos de diretório. Os parâmetros $count e $search não estão disponíveis no momento em locatários do Azure AD B2C.
Por padrão, apenas um conjunto limitado de propriedades é retornado (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname e userPrincipalName).Para retornar um conjunto de propriedades alternativo, especifique o conjunto desejado de propriedades de usuário usando o parâmetro de consulta $select OData. Por exemplo, para retornardisplayName, givenName e postalCode, adicione o seguinte à sua consulta $select=displayName,givenName,postalCode.
As propriedades de extensão também dão suporte a parâmetros de consulta da seguinte maneira:
Tipo de extensão
Comentários
onPremisesExtensionAttributes 1-15
Retornado somente com $select. Suporte $filter (eq, ne, e eq no null valores).
Extensões de esquema
Retornado somente com $select. Suporte $filter (eq, ne, e eq no null valores).
Extensões abertas
Retornado somente com $expand, ou seja, users?$expand=extensions.
Extensões de diretório
Retornado somente com $select. Suporte $filter (eq, ne, e eq no null valores).
Determinadas propriedades não podem ser retornadas em uma coleção de usuários. As propriedades a seguir só têm suporte ao recuperar um único usuário: aboutMe, birthday, hireDate, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills, mailboxSettings.
As propriedades a seguir não têm suporte em contas pessoais da Microsoft e serão null: aboutMe, birthday, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills, streetAddress.
eventualmente. Este cabeçalho e $count são necessários quando se utiliza $search, ou em uso específico de $filter. Para obter mais informações sobre o uso de ConsistencyLevel e $count, consulte Recursos avançados de consulta em objetos de diretório.
Corpo da solicitação
Não forneça um corpo de solicitação para esse método.
Resposta
Se bem-sucedido, este método retorna um código de resposta 200 OK e uma coleção de objetos user no corpo da resposta. Se uma coleção grande de usuários for retornada, você poderá usar a paginação no seu aplicativo.
Tentar usar $select na /users coleção para recuperar propriedades que não podem ser retornadas em uma coleção de usuários (por exemplo, a solicitação ../users?$select=aboutMe) retorna um 501 Not Implemented código de erro.
// 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();
Exemplo 2: Obter uma conta de usuário usando um nome de entrada
Solicitação
O exemplo a seguir mostra uma solicitação.
Observação: ao filtrar em issuerAssignedId, você deve fornecer emissor e issuerAssignedId. Entretanto, o valor do emissor será ignorado em determinados cenários. Para obter mais informações sobre filtragem em identidades, consulte objectIdentity resource type
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')";
});
O exemplo a seguir mostra uma solicitação. Esta solicitação exige o cabeçalho ConsistencyLevel definido como eventual porque $count está na solicitação. Para obter mais informações sobre o uso de ConsistencyLevel e $count, consulte Recursos avançados de consulta em objetos de diretório.
Observação: os parâmetros de consulta $count e $search não estão disponíveis atualmente nos locatários do Azure Active Directory 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");
});
Exemplo 4: utilize $filter e $top para obter um usuário com um nome de exibição que comece com a letra 'a', incluindo uma contagem de objetos retornados
Solicitação
O exemplo a seguir mostra uma solicitação. Esta solicitação exige o cabeçalho ConsistencyLevel definido como eventual e a cadeia de caracteres de consulta $count=true porque a solicitação tem os parâmetros de consulta $orderby e $filter. Para obter mais informações sobre o uso de ConsistencyLevel e $count, consulte Recursos avançados de consulta em objetos de diretório.
Observação: os parâmetros de consulta $count e $search não estão disponíveis atualmente nos locatários do Azure Active Directory B2C.
GET https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName,'a')&$orderby=displayName&$count=true&$top=1
ConsistencyLevel: eventual
Resposta
O exemplo a seguir mostra a resposta.
Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.
Exemplo 5: use $filter para obter todos os usuários com um email que termina com 'a@contoso.com', incluindo uma contagem de objetos retornados, com os resultados ordenados pelo usuárioPrincipalName
Solicitação
O exemplo a seguir mostra uma solicitação. Esta solicitação exige o cabeçalho ConsistencyLevel definido como eventual e a cadeia de consulta $count=true porque a solicitação tem os parâmetros de consulta $orderby e $filter, e também usa o operador endsWith. Para obter mais informações sobre o uso de ConsistencyLevel e $count, consulte Recursos avançados de consulta em objetos de diretório.
Observação: os parâmetros de consulta $count e $search não estão disponíveis atualmente nos locatários do Azure Active Directory 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");
});
Exemplo 6: utilize $pesquisa para obter usuários com nomes de exibição que contenham as letras 'wa', incluindo uma contagem de objetos retornados
Solicitação
O exemplo a seguir mostra uma solicitação. Esta solicitação exige o cabeçalho ConsistencyLevel definido como eventual porque $search está na solicitação. Para obter mais informações sobre o uso de ConsistencyLevel e $count, consulte Recursos avançados de consulta em objetos de diretório.
Observação: os parâmetros de consulta $count e $search não estão disponíveis atualmente nos locatários do Azure Active Directory 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");
});
Exemplo 7: Use $search para obter usuários com nomes de exibição que contenham as letras 'wa' ou as letras 'ad', incluindo uma contagem de objetos retornados
Solicitação
O exemplo a seguir mostra uma solicitação. Esta solicitação exige o cabeçalho ConsistencyLevel definido como eventual porque $search está na solicitação. Para obter mais informações sobre o uso de ConsistencyLevel e $count, consulte Recursos avançados de consulta em objetos de diretório.
Observação: os parâmetros de consulta $count e $search não estão disponíveis atualmente nos locatários do Azure Active Directory B2C.
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --search ""displayName:wa" OR "displayName:ad"" --count "true" --consistency-level "eventual"
Exemplo 8: Obter usuários convidados (B2B) de um locatário ou domínio específico por userPrincipalName
Solicitação
O exemplo a seguir mostra uma solicitação. O valor userPrincipalName para usuários convidados (colaboração B2B) sempre contém o identificador "#EXT#". Por exemplo, o usuárioPrincipalName de um usuário em seu locatário doméstico é AdeleV@adatum.com. Quando você convida o usuário a colaborar em seu locatário, contoso.com, seu usuárioPrincipalName em seu locatário é "AdeleV_adatum.com#EXT#@contoso.com".
Essa solicitação requer o cabeçalho ConsistencyLevel definido como eventual e a $count=true cadeia de caracteres de consulta porque a solicitação inclui o operador endsWith. Para obter mais informações sobre o uso de ConsistencyLevel e $count, consulte Recursos avançados de consulta em objetos de diretório.
NOTA: Você deve codificar o caractere reservado "#" no valor userPrincipalName como "%23" na URL de solicitação. Para obter mais informações, confira Codificar caracteres especiais.
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");
});
Exemplo 9: use $filter para obter usuários que recebem uma licença específica
Solicitação
O exemplo a seguir mostra uma solicitação.
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"};
});
Na resposta a seguir, a propriedade de extensão de esquema ext55gb1l09_msLearnCourses não está designada em dois dos objetos de usuário.
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
}
},
{}
]
}
Observação: você também pode aplicar $filter na propriedade de extensão do esquema para recuperar objetos em que uma propriedade na coleção corresponde a um valor especificado. A sintaxe é /users?$filter={schemaPropertyID}/{propertyName} eq 'value'. Por exemplo, GET /users?$select=ext55gb1l09_msLearnCourses&$filter=ext55gb1l09_msLearnCourses/courseType eq 'Developer'. Os eq e not operadores são compatíveis.
Exemplo 11: obter usuários incluindo seu último tempo de entrada
Solicitação
O exemplo a seguir mostra uma solicitação. Os detalhes da propriedade signInActivity exigem uma licença P1 ou P2 Microsoft Entra ID e a permissão AuditLog.Read.All.
Nota: Quando você especifica $select=signInActivity ou $filter=signInActivity ao listar usuários, o tamanho máximo da página para $top é 120. Solicitações com $top configuração superior a 120 retornarão páginas com até 120 usuários. signInActivity dá suporte (eq, , ne, not, ge, le) mas não com outras $filter propriedades filtradas.
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"};
});
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.