functions/group/Get-PSEntraIDGroup.ps1
|
function Get-PSEntraIDGroup { <# .SYNOPSIS Get the properties of the specified group. .DESCRIPTION Get the properties of the specified group. .PARAMETER Identity Mailnicname, Mail or Id of the group attribute populated in tenant/directory. .PARAMETER DisplayName DisplayName of the group attribute populated in tenant/directory. .PARAMETER Filter Filter expressions of accounts in tenant/directory. .PARAMETER AdvancedFilter Switch advanced filter for filtering accounts in tenant/directory. .PARAMETER All Return all accounts in tenant/directory. .PARAMETER EnableException This parameter disables user-friendly warnings and enables the throwing of exceptions. This is less user friendly, but allows catching exceptions in calling scripts. .EXAMPLE PS C:\> Get-PSEntraIDGroup -Identity group1 Get properties of Azure AD group group1 .NOTES Piping into Select-Object -First N logs a warning that is not a failure: WARNING: [<cmdlet>] Failed to: ... | The pipeline has been stopped The results are correct and complete. Select-Object stops the pipeline once it has what it asked for, and the next write throws PipelineStoppedException - normal termination, reported as an error only because the write happens inside a protected block. Materialise first if the warning is in the way: $items = @(<cmdlet> ...) $items | Select-Object -First 3 or filter server-side with -Filter instead of trimming client-side. Not silenced on purpose: the only fix that works is to collect the whole result before emitting any of it, which would cost streaming on every read. #> [OutputType('PSMicrosoftEntraID.Groups.Group')] [CmdletBinding(DefaultParameterSetName = 'Identity')] param( [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'Identity')] [Alias("Id", "GroupId", "TeamId", "MailNickName")] [ValidateGroupIdentity()] [string[]] $Identity, [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $false, ParameterSetName = 'DisplayName')] [ValidateNotNullOrEmpty()] [string[]] $DisplayName, [Parameter(Mandatory = $True, ParameterSetName = 'Filter')] [ValidateNotNullOrEmpty()] [string] $Filter, [Parameter(Mandatory = $false, ParameterSetName = 'Filter')] [ValidateNotNullOrEmpty()] [switch] $AdvancedFilter, [Parameter(Mandatory = $True, ParameterSetName = 'All')] [ValidateNotNullOrEmpty()] [switch] $All, [Parameter()] [switch] $EnableException ) begin { [string] $service = Get-PSFConfigValue -FullName ('{0}.Settings.DefaultService' -f $script:ModuleName) Assert-EntraConnection -Service $service -Cmdlet $PSCmdlet [hashtable] $query = @{ '$count' = 'true' '$top' = Get-PSFConfigValue -FullName ('{0}.Settings.GraphApiQuery.PageSize' -f $script:ModuleName) '$select' = ((Get-PSFConfig -Module $script:ModuleName -Name Settings.GraphApiQuery.Select.Group).Value -join ',') } [int] $commandRetryCount = Get-PSFConfigValue -FullName ('{0}.Settings.Command.RetryCount' -f $script:ModuleName) [System.TimeSpan] $commandRetryWait = New-TimeSpan -Seconds (Get-PSFConfigValue -FullName ('{0}.Settings.Command.RetryWaitInSeconds' -f $script:ModuleName)) } process { switch ($PSCmdlet.ParameterSetName) { 'Identity' { foreach ($group in $Identity) { [hashtable] $mailNickNameQuery = @{ '$top' = Get-PSFConfigValue -FullName ('{0}.Settings.GraphApiQuery.PageSize' -f $script:ModuleName) '$select' = ((Get-PSFConfig -Module $script:ModuleName -Name Settings.GraphApiQuery.Select.Group).Value -join ',') } $mailNickNameQuery['$Filter'] = ("mailNickName eq '{0}'" -f (ConvertTo-ODataFilterString -Value $group)) Invoke-PSFProtectedCommand -ActionString 'Group.Get' -ActionStringValues $group -Target (Get-PSFLocalizedString -Module $script:ModuleName -Name Identity.Platform) -ScriptBlock { [PSMicrosoftEntraID.Groups.Group[]] $mailNickName = ConvertFrom-RestGroup -InputObject (Invoke-EntraRequest -Service $service -Path ('groups') -Query $mailNickNameQuery -Method Get -ErrorAction Stop) if (-not([object]::Equals($mailNickName, $null))) { [string] $groupId = $mailNickName[0].Id } else { [string] $groupId = $group } ConvertFrom-RestGroup -InputObject (Invoke-EntraRequest -Service $service -Path ('groups/{0}' -f $groupId) -Query $query -Method Get -ErrorAction Stop) } -EnableException:$EnableException -Continue -PSCmdlet $PSCmdlet -RetryCount $commandRetryCount -RetryWait $commandRetryWait -WhatIf:$false if (Test-PSFFunctionInterrupt) { return } } } 'DisplayName' { foreach ($group in $DisplayName) { $query['$Filter'] = ("startswith(displayName,'{0}')" -f (ConvertTo-ODataFilterString -Value $group)) Invoke-PSFProtectedCommand -ActionString 'Group.Get' -ActionStringValues $group -Target (Get-PSFLocalizedString -Module $script:ModuleName -Name Identity.Platform) -ScriptBlock { ConvertFrom-RestGroup -InputObject (Invoke-EntraRequest -Service $service -Path ('groups') -Query $query -Method Get -ErrorAction Stop) } -EnableException:$EnableException -PSCmdlet $PSCmdlet -Continue -RetryCount $commandRetryCount -RetryWait $commandRetryWait -WhatIf:$false if (Test-PSFFunctionInterrupt) { return } } } 'Filter' { $query['$Filter'] = $Filter if ($AdvancedFilter.IsPresent) { [hashtable] $header = @{} $header['ConsistencyLevel'] = 'eventual' Invoke-PSFProtectedCommand -ActionString 'Group.Filter' -ActionStringValues $Filter -Target (Get-PSFLocalizedString -Module $script:ModuleName -Name Identity.Platform) -ScriptBlock { ConvertFrom-RestGroup -InputObject (Invoke-EntraRequest -Service $service -Path ('groups') -Query $query -Method Get -Header $header -ErrorAction Stop) } -EnableException:$EnableException -PSCmdlet $PSCmdlet -Continue -RetryCount $commandRetryCount -RetryWait $commandRetryWait -WhatIf:$false } else { Invoke-PSFProtectedCommand -ActionString 'Group.Filter' -ActionStringValues $Filter -Target (Get-PSFLocalizedString -Module $script:ModuleName -Name Identity.Platform) -ScriptBlock { ConvertFrom-RestGroup -InputObject (Invoke-EntraRequest -Service $service -Path ('groups') -Query $query -Method Get -ErrorAction Stop) } -EnableException:$EnableException -PSCmdlet $PSCmdlet -Continue -RetryCount $commandRetryCount -RetryWait $commandRetryWait -WhatIf:$false } if (Test-PSFFunctionInterrupt) { return } } 'All' { if ($All.IsPresent) { Invoke-PSFProtectedCommand -ActionString 'Group.List' -ActionStringValues 'All' -Target (Get-PSFLocalizedString -Module $script:ModuleName -Name Identity.Platform) -ScriptBlock { ConvertFrom-RestGroup -InputObject (Invoke-EntraRequest -Service $service -Path ('groups') -Query $query -Method Get -ErrorAction Stop) } -EnableException:$EnableException -PSCmdlet $PSCmdlet -Continue -RetryCount $commandRetryCount -RetryWait $commandRetryWait -WhatIf:$false if (Test-PSFFunctionInterrupt) { return } } } } } end {} } |