Public/Groups/Get-KB4Group.ps1
|
<# .SYNOPSIS Gets KnowBe4 groups. .DESCRIPTION Retrieves groups from the KnowBe4 Reporting API. Without Id, the command returns a page of groups or all groups when All is specified. With Id, the command returns a specific group. Normal output unwraps KnowBe4 page data and returns group objects. Use Raw to inspect the full response envelope and page wrapper. .PARAMETER Id The KnowBe4 group ID to retrieve. .PARAMETER Status Filters list results by group status. Valid values are Active and Archived. .PARAMETER All Retrieves all available pages. .PARAMETER PageSize The number of groups to request per page. Valid range is 1 through 500. .PARAMETER Page The page number to request when using page-based pagination. .PARAMETER Cursor The cursor value to request. Use 'true' to start cursor pagination manually. .PARAMETER UsePagePagination Uses page-based pagination when All is specified. Cursor pagination is preferred. .PARAMETER Raw Returns the full PSKB4Reporting response envelope instead of unwrapped group objects. .EXAMPLE Get-KB4Group -Status Active Gets the first page of active groups. .EXAMPLE Get-KB4Group -All -PageSize 500 Gets all groups using cursor pagination. .EXAMPLE Get-KB4Group -Id 123 Gets a specific KnowBe4 group. .OUTPUTS PSCustomObject. #> function Get-KB4Group { [CmdletBinding(DefaultParameterSetName = 'List')] param( [Parameter(Mandatory, ParameterSetName = 'ById', ValueFromPipelineByPropertyName)] [Alias('GroupId')] [int] $Id, [Parameter(ParameterSetName = 'List')] [ValidateSet('Active', 'Archived')] [string] $Status, [Parameter(ParameterSetName = 'List')] [switch] $All, [Parameter(ParameterSetName = 'List')] [ValidateRange(1, 500)] [int] $PageSize = 100, [Parameter(ParameterSetName = 'List')] [ValidateRange(1, [int]::MaxValue)] [int] $Page, [Parameter(ParameterSetName = 'List')] [string] $Cursor, [Parameter(ParameterSetName = 'List')] [switch] $UsePagePagination, [Parameter()] [switch] $Raw ) process { if ($PSCmdlet.ParameterSetName -eq 'ById') { $path = '/v1/groups/{0}' -f (Format-KB4PathValue -Value $Id) return Get-KB4ResponseBody -Response (Invoke-KB4Request -Path $path) -Raw:$Raw } $query = @{} if ($Status) { $query['status'] = $Status.ToLowerInvariant() } $pagedParameters = @{ Path = '/v1/groups' Query = $query All = $All PageSize = $PageSize UsePagePagination = $UsePagePagination Raw = $Raw } if ($PSBoundParameters.ContainsKey('Page')) { $pagedParameters['Page'] = $Page } if ($PSBoundParameters.ContainsKey('Cursor')) { $pagedParameters['Cursor'] = $Cursor } Invoke-KB4PagedRequest @pagedParameters } } |