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 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.
        RawData contains the original VM payload without API metadata.
    #>


    [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
    )

    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

            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

        foreach ($vmData in $Response.data) {
            [PrismVM]::new($vmData, $PrismSessionConfig.Name)
        }
    }
}