Public/Start-PrismVM.ps1
|
function Start-PrismVM { <# .SYNOPSIS Turns on a VM. .DESCRIPTION Powers on the Virtual Machine with the given external identifier. This is a conditional operation: the v4 API requires the current ETag of the VM (supplied as an If-Match header). This function first performs a GET to obtain a fresh ETag for each VM. .NOTES Implements: POST /vmm/v{ApiVersion}/ahv/config/vms/{extId}/$actions/power-on (operationId: powerOnVm) 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 globally unique identifier (UUID) of the VM to power on. .PARAMETER VM A PrismVM object, supplied explicitly or through the pipeline. Uses its ExtId and originating session unless -PrismSession is specified. .EXAMPLE Start-PrismVM -ExtId 'e731e375-c1de-4a2b-8c86-19a8b6968f3a' .OUTPUTS A PrismTask reference describing the asynchronous power-on task. #> [CmdletBinding(SupportsShouldProcess = $true, DefaultParameterSetName = 'ByVM')] [OutputType([PrismTask])] param( [Parameter(Mandatory = $false, HelpMessage = 'Prism Session Name')][string]$PrismSession, [Parameter(Mandatory = $true, ParameterSetName = 'ById', ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = 'VM external identifier (UUID)')] [Alias('Id', 'VmExtId')][ValidateNotNullOrEmpty()][string]$ExtId, [Parameter(Mandatory = $true, ParameterSetName = 'ByVM', ValueFromPipeline = $true)] [ValidateNotNull()][PrismVM]$VM ) process { $vmId = if ($PSCmdlet.ParameterSetName -eq 'ByVM') { $VM.ExtId } else { $ExtId } if ([string]::IsNullOrWhiteSpace($vmId)) { throw 'A VM ExtId is required.' } $sessionName = if ($PSCmdlet.ParameterSetName -eq 'ByVM' -and -not $PSBoundParameters.ContainsKey('PrismSession')) { $VM.PrismSession } else { $PrismSession } if (-not $PSCmdlet.ShouldProcess($vmId, 'Power on VM')) { return } $PrismSessionConfig = Get-PrismSession $sessionName $vmPath = 'vmm/v{0}/ahv/config/vms/{1}' -f $PrismSessionConfig.ApiVersion, $vmId $requestETag = Get-PrismResourceEtag -PrismSession $PrismSessionConfig.Name -Path $vmPath $headers = @{ 'If-Match' = $requestETag 'NTNX-Request-Id' = (New-Guid).Guid } $RequestSplat = @{ PrismSession = $PrismSessionConfig.Name Method = 'POST' Path = ('{0}/$actions/power-on' -f $vmPath) Header = $headers } $Response = Invoke-PrismRequest @RequestSplat return [PrismTask]::new($Response.data, $PrismSessionConfig.Name) } } |