Public/Users/Get-KB4User.ps1
|
<# .SYNOPSIS Gets KnowBe4 users. .DESCRIPTION Retrieves users from the KnowBe4 Reporting API. Without Id, the command returns a page of users or all users when All is specified. With Id, the command returns a specific user. Normal output unwraps KnowBe4 page data and returns user objects. Use Raw to inspect the full response envelope and page wrapper. .PARAMETER Id The KnowBe4 user ID to retrieve. .PARAMETER Status Filters list results by user status. Valid values are Active and Archived. .PARAMETER GroupId Filters list results to users in the specified KnowBe4 group. .PARAMETER ExpandGroup Requests expanded group details in the user response. .PARAMETER All Retrieves all available pages. .PARAMETER PageSize The number of users 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 because KnowBe4 plans to deprecate page-based pagination. .PARAMETER Raw Returns the full PSKB4Reporting response envelope instead of unwrapped user objects. .EXAMPLE Get-KB4User -Status Active -PageSize 100 Gets the first page of active users. .EXAMPLE Get-KB4User -Status Active -All -PageSize 500 Gets all active users using cursor pagination. .EXAMPLE Get-KB4User -Id 12345 Gets a specific KnowBe4 user. .OUTPUTS PSCustomObject. #> function Get-KB4User { [CmdletBinding(DefaultParameterSetName = 'List')] param( [Parameter(Mandatory, ParameterSetName = 'ById', ValueFromPipelineByPropertyName)] [Alias('UserId')] [int] $Id, [Parameter(ParameterSetName = 'List')] [ValidateSet('Active', 'Archived')] [string] $Status, [Parameter(ParameterSetName = 'List')] [int] $GroupId, [Parameter(ParameterSetName = 'List')] [switch] $ExpandGroup, [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/users/{0}' -f (Format-KB4PathValue -Value $Id) return Get-KB4ResponseBody -Response (Invoke-KB4Request -Path $path) -Raw:$Raw } $query = @{} if ($Status) { $query['status'] = $Status.ToLowerInvariant() } Add-KB4QueryParameter -Query $query -Name 'group_id' -Value $GroupId if ($ExpandGroup) { $query['expand'] = 'group' } $pagedParameters = @{ Path = '/v1/users' 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 } } |