Public/Phishing/Get-KB4PhishingRecipient.ps1
|
<# .SYNOPSIS Gets recipient results for a KnowBe4 phishing security test. .DESCRIPTION Retrieves phishing recipient results for a specific KnowBe4 phishing security test. Without Id, the command returns a page of recipient results or all recipient results when All is specified. With Id, the command returns a specific recipient result. Normal output unwraps KnowBe4 page data and returns recipient result objects. Use Raw to inspect the full response envelope and page wrapper. .PARAMETER SecurityTestId The KnowBe4 phishing security test ID. This parameter also accepts the alias PstId. .PARAMETER Id The recipient result ID. This parameter also accepts the alias RecipientId. .PARAMETER CampaignType Filters for a phishing campaign type. The current supported value is Callback. .PARAMETER All Retrieves all available pages. .PARAMETER PageSize The number of recipient results 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 recipient result objects. .EXAMPLE Get-KB4PhishingRecipient -SecurityTestId 67890 -PageSize 100 Gets recipient results for phishing security test 67890. .EXAMPLE Get-KB4PhishingRecipient -SecurityTestId 67890 -Id 555 Gets a specific recipient result. .OUTPUTS PSCustomObject. #> function Get-KB4PhishingRecipient { [CmdletBinding(DefaultParameterSetName = 'List')] param( [Parameter(Mandatory, ValueFromPipelineByPropertyName)] [Alias('PstId')] [int] $SecurityTestId, [Parameter(Mandatory, ParameterSetName = 'ById', ValueFromPipelineByPropertyName)] [Alias('RecipientId')] [int] $Id, [Parameter()] [ValidateSet('Callback')] [string] $CampaignType, [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 { $query = @{} if ($CampaignType) { $query['campaign_type'] = $CampaignType.ToLowerInvariant() } if ($PSCmdlet.ParameterSetName -eq 'ById') { $path = '/v1/phishing/security_tests/{0}/recipients/{1}' -f (Format-KB4PathValue -Value $SecurityTestId), (Format-KB4PathValue -Value $Id) return Get-KB4ResponseBody -Response (Invoke-KB4Request -Path $path -Query $query) -Raw:$Raw } $path = '/v1/phishing/security_tests/{0}/recipients' -f (Format-KB4PathValue -Value $SecurityTestId) $pagedParameters = @{ Path = $path 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 } } |