Public/Get-PrismTask.ps1
|
function Get-PrismTask { <# .SYNOPSIS Gets the details of a Prism Central task. .DESCRIPTION Retrieves a task by its external identifier or refreshes a PrismTask object. Asynchronous VM power, OVA, and category association operations return PrismTask references; this function retrieves their progress and results. The task external identifier returned by those operations is base64-encoded in the reference's ExtId property. Pass that value directly, without decoding. .NOTES Implements: GET /prism/v{ApiVersion}/config/tasks/{extId} (operationId: getTaskById) Uses the selected session's ApiVersion for the endpoint. .PARAMETER PrismSession The server/FQDN of the PrismSession to use. May be omitted when only one session exists. .PARAMETER ExtId The external identifier of the task to retrieve. .PARAMETER Task A PrismTask to refresh, either explicitly or from the pipeline. Uses its ExtId and originating PrismSession unless -PrismSession is specified. .EXAMPLE $task = Start-PrismVM -ExtId $vmId Get-PrismTask -Task $task .OUTPUTS A PrismTask describing the current task state. #> [CmdletBinding(DefaultParameterSetName = 'ByTask')] [OutputType([PrismTask])] param( [Parameter(Mandatory = $true, ParameterSetName = 'ById', ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = 'Task external identifier')] [Alias('Id', 'TaskExtId')][ValidateNotNullOrEmpty()][string]$ExtId, [Parameter(Mandatory = $true, ParameterSetName = 'ByTask', ValueFromPipeline = $true)] [ValidateNotNull()][PrismTask]$Task, [Parameter(Mandatory = $false, HelpMessage = 'Prism Session Name')][string]$PrismSession, [Parameter(DontShow)][Nullable[DateTimeOffset]]$Deadline ) process { $taskId = if ($PSCmdlet.ParameterSetName -eq 'ByTask') { $Task.ExtId } else { $ExtId } if ([string]::IsNullOrWhiteSpace($taskId)) { throw 'A task ExtId is required.' } $sessionName = if ($PSCmdlet.ParameterSetName -eq 'ByTask' -and -not $PSBoundParameters.ContainsKey('PrismSession')) { $Task.PrismSession } else { $PrismSession } $deadlineSplat = @{} if ($null -ne $Deadline) { $deadlineSplat.Deadline = $Deadline } $PrismSessionConfig = Get-PrismSession $sessionName @deadlineSplat $RequestSplat = @{ PrismSession = $PrismSessionConfig.Name Method = 'GET' Path = ('prism/v{0}/config/tasks/{1}' -f $PrismSessionConfig.ApiVersion, $taskId) } $Response = Invoke-PrismRequest @RequestSplat @deadlineSplat return [PrismTask]::new($Response.data, $PrismSessionConfig.Name) } } |