Public/Group/Get-Groups.ps1
|
<# .SYNOPSIS Retrieves Group(s) based on a set of parameters. .DESCRIPTION Retrieves one or more Group resources found under a given parent Organization and matches given search parameters. A user with GROUP.READ will be allowed to retrieve groups from an organization. For query by memberId of an identity that is assigned across organizations (such as SERVICE), this API retrieves all groups assigned to the identity irrespective of organization. Note: - Only users having administrator permissions on the parent Group can list the sub groups. - Search set shall contain child Groups found under the requested parent organization (non-recursive). - Any unknown parameters shall be ignored. .INPUTS Accepts the organization resource object .OUTPUTS An array of group resource objects .PARAMETER Org The organization resource object .PARAMETER Name An optional group name to use as filter .PARAMETER MemberType Filter by memeber type of either 'USER', 'DEVICE' or 'SERVICE' If this parameter is specified then the MemberId must be specified .PARAMETER MemberId Filter by members with this identifier If this parameter is specified then the MemberType must be specified .EXAMPLE $myorg = Get-Orgs | where { $_.Name -eq "MyOrg" } $myGroups = Get-Groups -Org $myOrg .EXAMPLE $myorg = Get-Orgs | where { $_.Name -eq "MyOrg" } $myNamedGroup = Get-Groups -Org $myOrg -Name "MyNamedGroup" .EXAMPLE $myorg = Get-Orgs | where { $_.Name -eq "MyOrg" } $myDeviceGroupForMember1 = Get-Groups -Org $myOrg -MemberType "DEVICE" -MemberId "1" .LINK https://www.hsdp.io/documentation/identity-and-access-management-iam/api-documents/resource-reference-api/user-api/group-api#/Group%20Management/get_authorize_identity_Group .NOTES GET: GET: /authorize/identity/Group v1 The API does does not support searching for group names that contain a space or special characters Because this API does not use a consistient resource format, the resource is transofrmed to match the Get-Group cmdlet format as close a possible for the available fields. Form example, it does not contain the meta element as this is not available on the response. #> function Get-Groups { [CmdletBinding()] [OutputType([PSObject])] param( [Parameter(Mandatory, Position = 0, ValueFromPipeline)] [ValidateNotNullOrEmpty()] [PSObject]$Org, [Parameter(Mandatory = $false, Position = 1)] [String]$Name, [Parameter(Mandatory = $false)] [ValidateSet('USER', 'DEVICE', 'SERVICE')] [String]$MemberType, [Parameter(Mandatory = $false)] [String]$MemberId ) begin { Write-Verbose "[$($MyInvocation.MyCommand.Name)] Function started" } process { Write-Debug "[$($MyInvocation.MyCommand.Name)] PSBoundParameters: $($PSBoundParameters | Out-String)" $params = "organizationId=$($Org.id)" if ($Name) { $params += "&name=$($Name)" } if ($MemberType -and $MemberId) { $params += "&memberType=$($MemberType)&memberId=$($MemberId)" } elseif (($MemberType -and -not $MemberId) -or (-not $MemberType -and $MemberId)) { throw "If either MemberType or MemberId is supplied then both must be supplied" } $response = (Invoke-GetRequest "/authorize/identity/Group?$($params)" -Version 1).entry | Select-Object -ExpandProperty resource # transform the result to match the resources in Get-Group Write-Output @($response | Select-Object @{Name="name";Expression={$_.groupName}}, ` @{name="description";Expression={$_.groupDescription}}, ` @{Name="managingOrganization";Expression={$_.orgId}}, ` @{name="id";Expression={$_._id}}) } end { Write-Verbose "[$($MyInvocation.MyCommand.Name)] Complete" } } |