Public/Get-PrismVM.ps1
|
function Get-PrismVM { <# .SYNOPSIS Lists Virtual Machines, or gets the configuration details of a single VM. .DESCRIPTION With no -ExtId, lists the Virtual Machines defined on the system using the v4 "List VMs" endpoint, supporting OData paging/filtering/ordering/selection. With -ExtId, retrieves the configuration details for a single VM using the "Get VM configuration details" endpoint. .NOTES Implements: GET /vmm/v{ApiVersion}/ahv/config/vms (operationId: listVms) GET /vmm/v{ApiVersion}/ahv/config/vms/{extId} (operationId: getVmById) Uses the selected session's ApiVersion for both endpoints. .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 retrieve. .PARAMETER VM A PrismVM to refresh, supplied explicitly or through the pipeline. Uses its ExtId and originating session unless -PrismSession is specified. .PARAMETER Raw Return the untouched API response, including metadata, instead of PrismVM objects. .PARAMETER Page ($page) Zero-based page number of the result set. .PARAMETER Limit ($limit) Maximum number of records to return (1-100, default 50). .PARAMETER Filter ($filter) An OData filter expression, e.g. "name eq 'MyVM'". .PARAMETER OrderBy ($orderby) An OData order-by expression, e.g. "name desc". .PARAMETER Select ($select) An OData select expression listing the properties to return. .EXAMPLE Get-PrismVM .EXAMPLE Get-PrismVM -Filter "startswith(name, 'web')" -Limit 100 .EXAMPLE Get-PrismVM -ExtId 'ba8da8d6-4ee5-440d-8703-206051443ccc' .OUTPUTS One PrismVM for ID/object lookup, or PrismVM objects for a list. With -Raw, the untouched API response. #> [CmdletBinding(DefaultParameterSetName = 'List')] [OutputType([PrismVM])] 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, [Parameter(ParameterSetName = 'List')][int]$Page, [Parameter(ParameterSetName = 'List')][ValidateRange(1, 100)][int]$Limit, [Parameter(ParameterSetName = 'List')][string]$Filter, [Parameter(ParameterSetName = 'List')][string]$OrderBy, [Parameter(ParameterSetName = 'List')][string]$Select, [Parameter()][switch]$Raw ) process { $sessionName = if ($PSCmdlet.ParameterSetName -eq 'ByVM' -and -not $PSBoundParameters.ContainsKey('PrismSession')) { $VM.PrismSession } else { $PrismSession } $vmId = if ($PSCmdlet.ParameterSetName -eq 'ByVM') { $VM.ExtId } else { $ExtId } if ($PSCmdlet.ParameterSetName -ne 'List' -and [string]::IsNullOrWhiteSpace($vmId)) { throw 'A VM ExtId is required.' } $PrismSessionConfig = Get-PrismSession $sessionName $vmPath = 'vmm/v{0}/ahv/config/vms' -f $PrismSessionConfig.ApiVersion if ($PSCmdlet.ParameterSetName -ne 'List') { $RequestSplat = @{ PrismSession = $PrismSessionConfig.Name Method = 'GET' Path = ('{0}/{1}' -f $vmPath, $vmId) } $response = Invoke-PrismRequest @RequestSplat if ($Raw) { return $response } return [PrismVM]::new($response.data, $PrismSessionConfig.Name) } $query = @{ '$page' = $PSBoundParameters.ContainsKey('Page') ? $Page : $null '$limit' = $PSBoundParameters.ContainsKey('Limit') ? $Limit : $null '$filter' = $Filter '$orderby' = $OrderBy '$select' = $Select } $RequestSplat = @{ PrismSession = $PrismSessionConfig.Name Method = 'GET' Path = $vmPath Query = $query } $Response = Invoke-PrismRequest @RequestSplat if ($Raw) { return $Response } foreach ($vmData in $Response.data) { [PrismVM]::new($vmData, $PrismSessionConfig.Name) } } } |