From 4f586a2172ceb3e52127dadb47c43b80fd6addb4 Mon Sep 17 00:00:00 2001 From: Marc Collins Date: Tue, 19 Nov 2024 16:49:12 +1100 Subject: [PATCH] Enhance NPrinting API functions: Add filtering parameters to Get-NPTasks, implement Get-NPUsers function, and improve GetNPFilter for URI encoding --- src/Private/GetNPFilter.ps1 | 3 + src/Public/Get-NPTasks.ps1 | 80 ++++++++++++--- src/Public/Get-NPUsers.ps1 | 172 ++++++++++++++++++++++++++++++++ src/Public/Invoke-NPRequest.ps1 | 2 + 4 files changed, 244 insertions(+), 13 deletions(-) create mode 100644 src/Public/Get-NPUsers.ps1 diff --git a/src/Private/GetNPFilter.ps1 b/src/Private/GetNPFilter.ps1 index e0141c8..7023cb1 100644 --- a/src/Private/GetNPFilter.ps1 +++ b/src/Private/GetNPFilter.ps1 @@ -8,6 +8,7 @@ function GetNPFilter { [string]$Value, [Parameter(Mandatory = $true, HelpMessage = "The existing filter string.")] + [AllowEmptyString()] [string]$Filter ) @@ -15,6 +16,8 @@ function GetNPFilter { if ($null -ne $Property -and $null -ne $Value) { # Replace wildcard character `*` with `%` $Value = $Value -replace '\*', '%' + # URI encode the value + $Value = [System.Web.HttpUtility]::UrlEncode($Value) # Determine the query separator based on the current filter $QuerySeparator = if ($Filter.StartsWith('?')) { '&' } else { '?' } diff --git a/src/Public/Get-NPTasks.ps1 b/src/Public/Get-NPTasks.ps1 index 377aee1..da76c72 100644 --- a/src/Public/Get-NPTasks.ps1 +++ b/src/Public/Get-NPTasks.ps1 @@ -13,9 +13,24 @@ .PARAMETER Name Specifies the name of the task to filter the results. +.PARAMETER appId + Specifies the ID of the app to filter the tasks. + +.PARAMETER type + Specifies the type of the task to filter the results. + .PARAMETER Executions Specifies whether to include execution details for each task. +.PARAMETER offset + Specifies the number of tasks to skip before starting to return results. + +.PARAMETER limit + Specifies the maximum number of tasks to retrieve. + +.PARAMETER sort + Specifies the field by which to sort the results. + .EXAMPLE Get-NPTasks @@ -36,6 +51,16 @@ This example retrieves all NPrinting tasks and includes execution details for each task. +.EXAMPLE + Get-NPTasks -appId "12345" + + This example retrieves all NPrinting tasks for the specified app ID. + +.EXAMPLE + Get-NPTasks -limit 10 -offset 5 + + This example retrieves a maximum of 10 NPrinting tasks, skipping the first 5. + .NOTES For more information, visit the NPrinting API documentation: https://help.qlik.com/en-US/nprinting/February2024/APIs/NP+API/index.html?page=60 @@ -44,30 +69,59 @@ https://help.qlik.com/en-US/nprinting/February2024/APIs/NP+API/index.html?page=60 #> function Get-NPTasks { - [CmdletBinding()] + [CmdletBinding(DefaultParameterSetName = 'Default')] param ( - [Parameter(HelpMessage = "Specifies the ID of the task to retrieve.")] + [Parameter(ParameterSetName = 'ByID', HelpMessage = 'Specifies the ID of the task to retrieve.', Mandatory = $true)] [string]$ID, - [Parameter(HelpMessage = "Specifies the name of the task to filter the results.")] + + [Parameter(ParameterSetName = 'Default', HelpMessage = 'Specifies the name of the task to filter the results.')] [string]$Name, - [Parameter(HelpMessage = "Specifies whether to include execution details for each task.")] - [switch]$Executions + + [Parameter(ParameterSetName = 'Default', HelpMessage = 'Specifies the ID of the app to filter the tasks.')] + [string]$appId, + + [Parameter(ParameterSetName = 'Default', HelpMessage = 'Specifies the type of the task to filter the results.')] + [string]$type, + + [Parameter(ParameterSetName = 'Default', HelpMessage = 'Specifies whether to include execution details for each task.')] + [Parameter(ParameterSetName = 'ByID', HelpMessage = 'Specifies whether to include execution details for each task.')] + [switch]$Executions, + + [Parameter(ParameterSetName = 'Default', HelpMessage = 'Specifies the number of tasks to skip before starting to return results.')] + [int32]$offset, + + [Parameter(ParameterSetName = 'Default', HelpMessage = 'Specifies the maximum number of tasks to retrieve.')] + [int32]$limit ) try { # Construct the base path $BasePath = 'tasks' - $Path = if ($ID) { "$BasePath/$ID" } else { $BasePath } - - # Add filter by name if specified - if ($Name) { - $Path = "$Path?filter=name eq '$Name'" + if ($ID) { + $APIPath = "$BasePath/$ID" + } else { + $Filter = '' + if ($PSBoundParameters.ContainsKey('appId')) { + $Filter = GetNPFilter -Filter $Filter -Property 'appId' -Value $appId + } + if ($PSBoundParameters.ContainsKey('Name')) { + $Filter = GetNPFilter -Filter $Filter -Property 'name' -Value $Name + } + if ($PSBoundParameters.ContainsKey('type')) { + $Filter = GetNPFilter -Filter $Filter -Property 'type' -Value $type + } + if ($PSBoundParameters.ContainsKey('offset')) { + $Filter = GetNPFilter -Filter $Filter -Property 'offset' -Value $offset.ToString() + } + if ($PSBoundParameters.ContainsKey('limit')) { + $Filter = GetNPFilter -Filter $Filter -Property 'limit' -Value $limit.ToString() + } + $APIPath = "$BasePath$Filter" } - - Write-Verbose "Request Path: $Path" + Write-Verbose "Request Path: $APIPath" # Fetch tasks from the API - $NPTasks = Invoke-NPRequest -Path $Path -method Get + $NPTasks = Invoke-NPRequest -Path $APIPath -method Get # Include execution details if requested if ($Executions) { diff --git a/src/Public/Get-NPUsers.ps1 b/src/Public/Get-NPUsers.ps1 new file mode 100644 index 0000000..7cfc37d --- /dev/null +++ b/src/Public/Get-NPUsers.ps1 @@ -0,0 +1,172 @@ +<# +.SYNOPSIS + Retrieves the list of NPrinting users. + +.DESCRIPTION + The Get-NPUsers function retrieves the list of users from the NPrinting server. + It uses the Invoke-NPRequest function to send a GET request to the 'users' endpoint of the NPrinting API. + Optional parameters can be specified to filter the results. + +.PARAMETER ID + Specifies the ID of the user to retrieve. + +.PARAMETER Name + Specifies the name of the user to filter the results. + +.PARAMETER Email + Specifies the email of the user to filter the results. + +.PARAMETER Role + Specifies the role of the user to filter the results. + +.PARAMETER Offset + Specifies the number of users to skip before starting to return results. + +.PARAMETER Limit + Specifies the maximum number of users to retrieve. + +.PARAMETER Filters + Specifies whether to include filter details for the user. + +.PARAMETER Groups + Specifies whether to include group details for the user. + +.PARAMETER Roles + Specifies whether to include role details for the user. + +.EXAMPLE + Get-NPUsers + + This example retrieves all NPrinting users. + +.EXAMPLE + Get-NPUsers -ID "12345" + + This example retrieves the NPrinting user with the specified ID. + +.EXAMPLE + Get-NPUsers -Name "John Doe" + + This example retrieves all NPrinting users with the name "John Doe". + +.EXAMPLE + Get-NPUsers -Email "john.doe@example.com" + + This example retrieves all NPrinting users with the specified email. + +.EXAMPLE + Get-NPUsers -Role "Admin" + + This example retrieves all NPrinting users with the specified role. + +.EXAMPLE + Get-NPUsers -Limit 10 -Offset 5 + + This example retrieves a maximum of 10 NPrinting users, skipping the first 5. + +.EXAMPLE + Get-NPUsers -ID "12345" -Filters + + This example retrieves the filters for the NPrinting user with the specified ID. + +.EXAMPLE + Get-NPUsers -ID "12345" -Groups + + This example retrieves the groups for the NPrinting user with the specified ID. + +.EXAMPLE + Get-NPUsers -ID "12345" -Roles + + This example retrieves the roles for the NPrinting user with the specified ID. + +.NOTES + For more information, visit the NPrinting API documentation: + https://help.qlik.com/en-US/nprinting/February2024/APIs/NP+API/index.html?page=63 + +.LINK + https://help.qlik.com/en-US/nprinting/February2024/APIs/NP+API/index.html?page=63 +#> +function Get-NPUsers { + [CmdletBinding(DefaultParameterSetName = 'Default')] + param ( + [Parameter(ParameterSetName = 'ByID', Mandatory = $true, HelpMessage = 'Specifies the ID of the user to retrieve.')] + [Parameter(ParameterSetName = 'Filters', Mandatory = $true, HelpMessage = 'Specifies the ID of the user to retrieve.')] + [Parameter(ParameterSetName = 'Groups', Mandatory = $true, HelpMessage = 'Specifies the ID of the user to retrieve.')] + [Parameter(ParameterSetName = 'Roles', Mandatory = $true, HelpMessage = 'Specifies the ID of the user to retrieve.')] + [string]$ID, + + [Parameter(ParameterSetName = 'Default', HelpMessage = 'Specifies the name of the user to filter the results.')] + [string]$Name, + + [Parameter(ParameterSetName = 'Default', HelpMessage = 'Specifies the email of the user to filter the results.')] + [string]$Email, + + [Parameter(ParameterSetName = 'Default', HelpMessage = 'Specifies the role of the user to filter the results.')] + [string]$Role, + + [Parameter(ParameterSetName = 'Default', HelpMessage = 'Specifies the number of users to skip before starting to return results.')] + [int32]$Offset, + + [Parameter(ParameterSetName = 'Default', HelpMessage = 'Specifies the maximum number of users to retrieve.')] + [int32]$Limit, + + [Parameter(ParameterSetName = 'Filters', Mandatory = $true, HelpMessage = 'Specifies whether to include filter details for the user.')] + [switch]$Filters, + + [Parameter(ParameterSetName = 'Groups', Mandatory = $true, HelpMessage = 'Specifies whether to include group details for the user.')] + [switch]$Groups, + + [Parameter(ParameterSetName = 'Roles', Mandatory = $true, HelpMessage = 'Specifies whether to include role details for the user.')] + [switch]$Roles + ) + + try { + # Construct the base path + $BasePath = 'users' + if ($ID) { + $APIPath = "$BasePath/$ID" + if ($Filters) { + $FiltersPath = "$APIPath/filters" + Write-Verbose "Fetching filters for user ID: $ID" + return Invoke-NPRequest -Path $FiltersPath -Method Get -Verbose:$VerbosePreference + } + if ($Groups) { + $GroupsPath = "$APIPath/groups" + Write-Verbose "Fetching groups for user ID: $ID" + return Invoke-NPRequest -Path $GroupsPath -Method Get -Verbose:$VerbosePreference + } + if ($Roles) { + $RolesPath = "$APIPath/roles" + Write-Verbose "Fetching roles for user ID: $ID" + return Invoke-NPRequest -Path $RolesPath -Method Get -Verbose:$VerbosePreference + } + } else { + $Filter = '' + if ($PSBoundParameters.ContainsKey('Name')) { + $Filter = GetNPFilter -Filter $Filter -Property 'name' -Value $Name + } + if ($PSBoundParameters.ContainsKey('Email')) { + $Filter = GetNPFilter -Filter $Filter -Property 'email' -Value $Email + } + if ($PSBoundParameters.ContainsKey('Role')) { + $Filter = GetNPFilter -Filter $Filter -Property 'role' -Value $Role + } + if ($PSBoundParameters.ContainsKey('Offset')) { + $Filter = GetNPFilter -Filter $Filter -Property 'offset' -Value $Offset.ToString() + } + if ($PSBoundParameters.ContainsKey('Limit')) { + $Filter = GetNPFilter -Filter $Filter -Property 'limit' -Value $Limit.ToString() + } + $APIPath = "$BasePath$Filter" + } + Write-Verbose "Request Path: $APIPath" + + # Fetch users from the API + $NPUsers = Invoke-NPRequest -Path $APIPath -Method Get -Verbose:$VerbosePreference + + return $NPUsers + + } catch { + Write-Error "Failed to retrieve NPUsers: $_" + } +} \ No newline at end of file diff --git a/src/Public/Invoke-NPRequest.ps1 b/src/Public/Invoke-NPRequest.ps1 index dbc04c6..f7f69d7 100644 --- a/src/Public/Invoke-NPRequest.ps1 +++ b/src/Public/Invoke-NPRequest.ps1 @@ -53,6 +53,7 @@ #> function Invoke-NPRequest { + [CmdletBinding(DefaultParameterSetName = 'Default')] param ( [Parameter(Mandatory = $true, Position = 0)] [string]$Path, @@ -93,6 +94,7 @@ function Invoke-NPRequest { if (-not $NPEnv) { Write-Warning 'Attempting to establish Default connection' Connect-NPrinting + $NPEnv = $script:NPEnv } # Build query parameters