Get-EntraUser
Obtém um usuário.
Sintaxe
GetQuery (Predefinição)
Get-EntraUser
[-Filter <String>]
[-All]
[-Top <Int32>]
[-PageSize <Int32>]
[-Property <String[]>]
[<CommonParameters>]
GetByValue
Get-EntraUser
[-SearchString <String>]
[-All]
[-Property <String[]>]
[<CommonParameters>]
GetById
Get-EntraUser
-UserId <String>
[-All]
[-Property <String[]>]
[<CommonParameters>]
GetFiltered
Get-EntraUser
[-All]
[-Top <Int32>]
[-PageSize <Int32>]
[-EnabledFilter <String>]
[-HasErrorsOnly]
[-LicenseReconciliationNeededOnly]
[-Synchronized]
[-UnlicensedUsersOnly]
[-Property <String[]>]
[<CommonParameters>]
Descrição
O Get-EntraUser cmdlet recebe um utilizador do Microsoft Entra ID.
Exemplos
Exemplo 1: Obtenha os três melhores utilizadores
Connect-Entra -Scopes 'User.Read.All'
Get-EntraUser -Top 3
DisplayName Id Mail UserPrincipalName
----------- -- ---- -----------------
Angel Brown cccccccc-2222-3333-4444-dddddddddddd AngelB@contoso.com AngelB@contoso.com
Avery Smith dddddddd-3333-4444-5555-eeeeeeeeeeee AveryS@contoso.com AveryS@contoso.com
Sawyer Miller eeeeeeee-4444-5555-6666-ffffffffffff SawyerM@contoso.com SawyerM@contoso.com
Este exemplo demonstra como obter os três primeiros utilizadores do Microsoft Entra ID. Você pode usar -Limit como um alias para -Top.
Exemplo 2: Obter um utilizador por ID
Connect-Entra -Scopes 'User.Read.All'
Get-EntraUser -UserId 'SawyerM@contoso.com'
DisplayName Id Mail UserPrincipalName
----------- -- ---- -----------------
Sawyer Miller bbbbbbbb-1111-2222-3333-cccccccccccc sawyerm@tenant.com sawyerm@tenant.com
Este comando recebe o utilizador especificado.
-
-UserIdEspecifica o ID como nome principal de utilizador (UPN) ou UserId.
Exemplo 3: Pesquisa entre utilizadores recuperados
Connect-Entra -Scopes 'User.Read.All'
Get-EntraUser -SearchString 'New'
DisplayName Id Mail UserPrincipalName
----------- -- ---- -----------------
New User88 bbbbbbbb-1111-2222-3333-cccccccccccc demo99@tenant.com
New User cccccccc-2222-3333-4444-dddddddddddd NewUser@tenant.com
Este cmdlet reúne todos os utilizadores que comparam o valor de SearchString com os primeiros caracteres em DisplayName ou UserPrincipalName.
Exemplo 4: Política de recuperação da palavra-passe do utilizador
Connect-Entra -Scopes 'User.Read.All'
Get-EntraUser -UserId 'SawyerM@contoso.com' `
-Property UserPrincipalName, PasswordPolicies |
Select-Object UserPrincipalName,
@{
Name = "PasswordNeverExpires"
Expression = { $_.PasswordPolicies -contains "DisablePasswordExpiration" }
}
userPrincipalName PasswordNeverExpires
----------------- --------------------
SawyerM@contoso.com True
Este exemplo mostra como obter a política de palavra-passe de um utilizador. Para atualizar, execute Get-EntraUser -UserId SawyerM@contoso.com | Set-EntraUser -PasswordPolicies DisablePasswordExpiration.
Exemplo 5: Relatório MFA por utilizador
Connect-Entra -scope 'User.Read.All', 'UserAuthenticationMethod.Read.All'
$users = Get-EntraUser -All -Select Id, UserPrincipalName, DisplayName
Write-Output "Amount of requests within `"fetchAll`": $($users.Count)"
$usersReport = [System.Collections.ArrayList]::new()
$users | ForEach-Object {
$userProperties = @{
Id = $_.Id
DisplayName = $_.DisplayName
UserPrincipalName = $_.UserPrincipalName
PerUserMFAState = (Get-EntraBetaUserAuthenticationRequirement -UserId $_.Id).PerUserMFAState
}
[void]$usersReport.Add([PSCustomObject]$userProperties)
}
$usersReport | Format-Table -AutoSize
UserPrincipalName DisplayName PerUserMFAState Id
----------------- ----------- --------------- --
AngelB@contoso.com Angel Brown enforced cccccccc-2222-3333-4444-dddddddddddd
AveryS@contoso.com Avery Smith disabled dddddddd-3333-4444-5555-eeeeeeeeeeee
SawyerM@contoso.com Sawyer Miller enforced eeeeeeee-4444-5555-6666-ffffffffffff
ChristieC@contoso.com Christie Cline enabled bbbbbbbb-1111-2222-3333-cccccccccccc
PattiF@contoso.com Patti Fernandez disabled aaaaaaaa-bbbb-cccc-1111-222222222222
Este exemplo mostra um relatório do estado MFA por utilizador.
Nota: A Microsoft recomenda o uso de políticas de Acesso Condicional e predefinidos de segurança para gerir a autenticação multifator (MFA) em vez de depender do MFA legado por utilizador.
Exemplo 6: Obter um utilizador pelo userPrincipalName
Connect-Entra -Scopes 'User.Read.All'
Get-EntraUser -Filter "userPrincipalName eq 'SawyerM@contoso.com'"
DisplayName Id Mail UserPrincipalName
----------- -- ---- -----------------
Sawyer Miller cccccccc-2222-3333-4444-dddddddddddd SawyerM@contoso.com
Este comando recebe o utilizador especificado.
Exemplo 7: Obter um utilizador pelo MailNickname
Connect-Entra -Scopes 'User.Read.All'
Get-EntraUser -Filter "startsWith(MailNickname,'Ada')"
DisplayName Id Mail UserPrincipalName
----------- -- ---- -----------------
Mark Adams bbbbbbbb-1111-2222-3333-cccccccccccc Adams@contoso.com Adams@contoso.com
Neste exemplo, recuperamos todos os utilizadores cujo MailNickname começa com Ada.
Exemplo 8: Obter LogInActivity de um utilizador
Connect-Entra -Scopes 'User.Read.All','AuditLog.Read.All'
Get-EntraUser -UserId 'SawyerM@contoso.com' -Property 'SignInActivity' | Select-Object -Property Id, DisplayName, UserPrincipalName -ExpandProperty 'SignInActivity'
lastNonInteractiveSignInRequestId : bbbbbbbb-1111-2222-3333-aaaaaaaaaaaa
lastSignInRequestId : cccccccc-2222-3333-4444-dddddddddddd
lastSuccessfulSignInDateTime : 9/9/2024 1:12:13 PM
lastNonInteractiveSignInDateTime : 9/9/2024 1:12:13 PM
lastSuccessfulSignInRequestId : bbbbbbbb-1111-2222-3333-aaaaaaaaaaaa
lastSignInDateTime : 9/7/2024 9:15:41 AM
id : aaaaaaaa-bbbb-cccc-1111-222222222222
displayName : Sawyer Miller
userPrincipalName : SawyerM@contoso.com
Este exemplo demonstra como recuperar a LogInActivity de um utilizador específico selecionando uma propriedade.
Exemplo 9: Listar utilizadores com contas desativadas
Connect-Entra -Scopes 'User.Read.All'
Get-EntraUser -Filter "accountEnabled eq false" | Select-Object DisplayName, Id, Mail, UserPrincipalName
DisplayName Id Mail UserPrincipalName
----------- -- ---- -----------------
New User cccccccc-2222-3333-4444-dddddddddddd NewUser@tenant.com
Este exemplo demonstra como recuperar todos os utilizadores com contas desativadas.
Exemplo 10: Listar utilizadores baseados num país específico
Connect-Entra -Scopes 'User.Read.All'
$usersInCanada = Get-EntraUser -Filter "Country eq 'Canada'"
$usersInCanada | Select-Object Id, DisplayName, UserPrincipalName, OfficeLocation, Country | Format-Table -AutoSize
Id DisplayName UserPrincipalName OfficeLocation Country
-- ----------- ----------------- -------------- -------
cccccccc-2222-3333-4444-dddddddddddd New User NewUser@tenant.com 23/2102 Canada
Este exemplo demonstra como recuperar todos os utilizadores sediados no Canadá.
Exemplo 11: Liste a contagem de utilizadores por departamento
Connect-Entra -Scopes 'User.Read.All'
$departmentCounts = Get-EntraUser -All | Group-Object -Property Department | Select-Object Name, @{Name="MemberCount"; Expression={$_.Count}}
$departmentCounts | Format-Table Name, MemberCount -AutoSize
Name MemberCount
---- -----------
7
Engineering 2
Executive Management 1
Finance 1
HR 1
Este exemplo demonstra como recuperar o número de utilizadores em cada departamento.
Exemplo 12: Listar utilizadores desativados com licenças ativas
Connect-Entra -Scopes 'User.Read.All'
$disabledUsersWithLicenses = Get-EntraUser -Filter "accountEnabled eq false" -All | Where-Object {
$_.AssignedLicenses -ne $null -and $_.AssignedLicenses.Count -gt 0
}
$disabledUsersWithLicenses | Select-Object Id, DisplayName, UserPrincipalName, AccountEnabled | Format-Table -AutoSize
Id DisplayName UserPrincipalName AccountEnabled
-- ----------- ----------------- --------------
cccccccc-2222-3333-4444-dddddddddddd New User NewUser@tenant.com False
Este exemplo demonstra como recuperar utilizadores com deficiência com licenças ativas.
Exemplo 13: Recuperar utilizadores convidados com licenças ativas
Connect-Entra -Scopes 'User.Read.All'
$guestUsers = Get-EntraUser -Filter "userType eq 'Guest'" -All
$guestUsersWithLicenses = foreach ($guest in $guestUsers) {
if ($guest.AssignedLicenses.Count -gt 0) {
[PSCustomObject]@{
Id = $guest.Id
DisplayName = $guest.DisplayName
UserPrincipalName = $guest.UserPrincipalName
AssignedLicenses = ($guest.AssignedLicenses | ForEach-Object { $_.SkuId }) -join ", "
}
}
}
$guestUsersWithLicenses | Format-Table Id, DisplayName, UserPrincipalName, AssignedLicenses -AutoSize
Id DisplayName UserPrincipalName AssignedLicenses
-- ----------- ----------------- ----------------
cccccccc-2222-3333-4444-dddddddddddd Sawyer Miller sawyerm_gmail.com#EXT#@contoso.com c42b9cae-ea4f-4ab7-9717-81576235ccac
Este exemplo demonstra como recuperar utilizadores convidados com licenças ativas.
Exemplo 14: Listar utilizadores com uma licença específica
Connect-Entra -Scopes 'User.Read.All'
$skuId = (Get-EntraSubscribedSku | Where-Object { $_.SkuPartNumber -eq 'POWERAPPS_DEV' }).SkuId
Get-EntraUser -Filter "assignedLicenses/any(l:l/skuId eq $skuId)" -Select id, displayName, userPrincipalName, userType, accountEnabled, assignedLicenses |
Select-Object id, displayName, userPrincipalName, userType, accountEnabled | Format-Table -AutoSize
id displayName userPrincipalName userType accountEnabled
-- ----------- ----------------- -------- --------------
cccccccc-2222-3333-4444-dddddddddddd Angel Brown AngelB@contoso.com Member True
dddddddd-3333-4444-5555-eeeeeeeeeeee Avery Smith AveryS@contoso.com Member True
Este exemplo demonstra como recuperar utilizadores com uma licença específica.
Exemplo 15: Recuperar utilizadores sem gestores
Connect-Entra -Scopes 'User.Read.All'
$allUsers = Get-EntraUser -All
$usersWithoutManagers = foreach ($user in $allUsers) {
$manager = Get-EntraUserManager -ObjectId $user.Id -ErrorAction SilentlyContinue
if (-not $manager) {
[PSCustomObject]@{
Id = $user.Id
DisplayName = $user.DisplayName
UserPrincipalName = $user.UserPrincipalName
}
}
}
$usersWithoutManagers | Format-Table Id, DisplayName, UserPrincipalName -AutoSize
Id DisplayName UserPrincipalName
-- ----------- -----------------
cccccccc-2222-3333-4444-dddddddddddd New User NewUser@tenant.com
bbbbbbbb-1111-2222-3333-cccccccccccc Sawyer Miller SawyerM@contoso.com
Este exemplo demonstra como recuperar utilizadores sem gestores.
Exemplo 16: Liste todos os utilizadores convidados
Connect-Entra -Scopes 'User.Read.All'
$guestUsers = Get-EntraUser -Filter "userType eq 'Guest'" -All
$guestUsers | Select-Object DisplayName, UserPrincipalName, Id, createdDateTime, creationType, accountEnabled, UserState | Format-Table -AutoSize
DisplayName UserPrincipalName Id CreatedDateTime CreationType AccountEnabled UserState
----------- ----------------- -- --------------- ------------ -------------- ---------
Sawyer Miller sawyerm_gmail.com#EXT#@contoso.com bbbbbbbb-1111-2222-3333-cccccccccccc 9/13/2024 6:37:33 PM Invitation True Accepted
Este exemplo demonstra como recuperar a lista de todos os utilizadores convidados.
Exemplo 17: Lista cinco utilizadores recentemente criados
Get-EntraUser -All | Sort-Object -Property createdDateTime -Descending | Select-Object -First 5
DisplayName Id Mail UserPrincipalName
----------- -- ---- -----------------
Angel Brown cccccccc-2222-3333-4444-dddddddddddd AngelB@contoso.com AngelB@contoso.com
Avery Smith dddddddd-3333-4444-5555-eeeeeeeeeeee AveryS@contoso.com AveryS@contoso.com
Sawyer Miller eeeeeeee-4444-5555-6666-ffffffffffff SawyerM@contoso.com SawyerM@contoso.com
Christie Cline bbbbbbbb-1111-2222-3333-cccccccccccc ChristieC@contoso.com ChristieC@contoso.com
Patti Fernandez aaaaaaaa-bbbb-cccc-1111-222222222222 PattiF@contoso.com PattiF@contoso.com
Este exemplo mostra como recuperar os utilizadores recentemente criados.
Exemplo 18: Lista de utilizadores com função de Administrador Global
Connect-Entra -Scopes 'User.Read.All', 'RoleManagement.Read.Directory'
$roleId = Get-EntraDirectoryRoleTemplate | Where-Object { $_.DisplayName -eq 'Global Administrator' } | Select-Object -ExpandProperty Id
$globalAdmins = Get-EntraDirectoryRoleAssignment -Filter "roleDefinitionId eq '$roleId'" | ForEach-Object {
Get-EntraUser -UserId $_.PrincipalId
}
$globalAdmins | Select-Object Id, DisplayName, UserPrincipalName, CreatedDateTime, AccountEnabled | Format-Table -AutoSize
id displayName userPrincipalName createdDateTime accountEnabled
-- ----------- ----------------- --------------- --------------
cccccccc-2222-3333-4444-dddddddddddd Angel Brown AngelB@contoso.com 3/7/2024 12:34:59 AM True
dddddddd-3333-4444-5555-eeeeeeeeeeee Avery Smith AveryS@contoso.com 10/1/2024 9:47:06 AM True
Este exemplo mostra como listar todos os utilizadores com um papel específico, como Global Administrator. A Microsoft recomenda atribuir o cargo de Administrador Global a menos de cinco pessoas para as melhores práticas. Consulte as melhores práticas.
Exemplo 19: Liste todos os utilizadores com sessões revogadas nos últimos 30 dias
Connect-Entra -Scopes 'User.Read.All'
$pastDate = (Get-Date).AddDays(-30).ToUniversalTime()
Get-EntraUser | Where-Object { $_.signInSessionsValidFromDateTime -ge $pastDate } |
Select-Object DisplayName, UserPrincipalName, signInSessionsValidFromDateTime
displayName userPrincipalName signInSessionsValidFromDateTime
----------- ----------------- -------------------------------
Angel Brown AngelB@contoso.com 03/03/2025 16:13:47
Avery Smith AveryS@contoso.com 03/03/2025 16:05:02
Este exemplo mostra como listar todos os utilizadores com sessões revogadas nos últimos 30 dias.
Parâmetros
-All
Liste todas as páginas.
Propriedades dos parâmetros
| Tipo: | System.Management.Automation.SwitchParameter |
| Valor predefinido: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Posto: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-EnabledFilter
Filtra os utilizadores com base no estado das suas contas. Os valores válidos são EnabledOnly e DisabledOnly. Quando especificado, o cmdlet adiciona uma accountEnabled restrição a qualquer expressão existente -Filter .
Propriedades dos parâmetros
| Tipo: | System.String |
| Valor predefinido: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | None |
Conjuntos de parâmetros
GetFiltered
| Posto: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Filter
Especifica uma instrução de filtro OData v4.0. Este parâmetro controla quais os objetos que são devolvidos. Detalhes sobre consultas com OData podem ser encontrados aqui.
Propriedades dos parâmetros
| Tipo: | System.String |
| Valor predefinido: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
GetQuery
| Posto: | Named |
| Obrigatório: | False |
| Valor do pipeline: | True |
| Valor do pipeline por nome de propriedade: | True |
| Valor dos restantes argumentos: | False |
-HasErrorsOnly
Devolve apenas utilizadores que apresentam um ou mais erros de provisionamento ou validação de serviços (manifestados através da serviceProvisioningErrors coleção). Use esta mudança para identificar rapidamente identidades que necessitam de remediação administrativa.
Propriedades dos parâmetros
| Tipo: | System.Management.Automation.SwitchParameter |
| Valor predefinido: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | None |
Conjuntos de parâmetros
GetFiltered
| Posto: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-LicenseReconciliationNeededOnly
Devolve apenas utilizadores cujos erros de provisionamento de serviços incluem questões relacionadas com licenças que indicam que a reconciliação de licenças é necessária (por exemplo, licenças insuficientes, violações de dependência, planos mutuamente exclusivos). Internamente, o cmdlet corresponde a padrões comuns de erro de licença para restringir o conjunto de resultados.
Propriedades dos parâmetros
| Tipo: | System.Management.Automation.SwitchParameter |
| Valor predefinido: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | None |
Conjuntos de parâmetros
GetFiltered
| Posto: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-PageSize
Quando -PageSize é especificado, o comando pode fazer múltiplas chamadas de rede para recuperar dados em blocos (páginas), continuando até atingir o limite definido por -Top ou -All, dependendo do que for utilizado.
Propriedades dos parâmetros
| Tipo: | System.Int32 |
| Valor predefinido: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Posto: | Named |
| Obrigatório: | False |
| Valor do pipeline: | True |
| Valor do pipeline por nome de propriedade: | True |
| Valor dos restantes argumentos: | False |
-Property
Especifica propriedades a devolver.
Propriedades dos parâmetros
| Tipo: | System.String[] |
| Valor predefinido: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | Select |
Conjuntos de parâmetros
(All)
| Posto: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-SearchString
Especifica uma cadeia de pesquisa.
Propriedades dos parâmetros
| Tipo: | System.String |
| Valor predefinido: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
GetVague
| Posto: | Named |
| Obrigatório: | False |
| Valor do pipeline: | True |
| Valor do pipeline por nome de propriedade: | True |
| Valor dos restantes argumentos: | False |
-Synchronized
Retorna apenas utilizadores sincronizados do Active Directory no local (aqueles com onPremisesSyncEnabled eq true). Isto é útil para distinguir identidades exclusivas da cloud de identidades geridas híbridas.
Propriedades dos parâmetros
| Tipo: | System.Management.Automation.SwitchParameter |
| Valor predefinido: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | None |
Conjuntos de parâmetros
GetFiltered
| Posto: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Top
Especifica o número máximo de registos a devolver.
Propriedades dos parâmetros
| Tipo: | System.Int32 |
| Valor predefinido: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | Limit |
Conjuntos de parâmetros
GetQuery
| Posto: | Named |
| Obrigatório: | False |
| Valor do pipeline: | True |
| Valor do pipeline por nome de propriedade: | True |
| Valor dos restantes argumentos: | False |
-UnlicensedUsersOnly
Devolve apenas utilizadores que não têm licenças atribuídas (assignedLicenses contagem é igual a 0). Isto ajuda a identificar utilizadores que podem ainda não ter acesso ao serviço necessário.
Propriedades dos parâmetros
| Tipo: | System.Management.Automation.SwitchParameter |
| Valor predefinido: | False |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | None |
Conjuntos de parâmetros
GetFiltered
| Posto: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-UserId
Especifica o ID (como Nome Principal de Utilizador (UPN) ou UserId) de um utilizador no Microsoft Entra ID.
Propriedades dos parâmetros
| Tipo: | System.String |
| Valor predefinido: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | IdentificadorDoObjeto, UPN, Identidade, Nome Principal do Utilizador |
Conjuntos de parâmetros
GetById
| Posto: | Named |
| Obrigatório: | True |
| Valor do pipeline: | True |
| Valor do pipeline por nome de propriedade: | True |
| Valor dos restantes argumentos: | False |
CommonParameters
Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.