Public/Add-PrismVMCategory.ps1
|
function Add-PrismVMCategory { <# .SYNOPSIS Associates one or more Categories with a VM. .DESCRIPTION Associates the given Category external identifier(s) with the VM using the dedicated "Associate categories to a VM" action. .NOTES Implements: POST /vmm/v{ApiVersion}/ahv/config/vms/{extId}/$actions/associate-categories (operationId: associateCategories) Uses the selected session's ApiVersion for the endpoint. Confirmed against the official Nutanix API reference (namespace 'vmm', version v4.3). Minimum supported versions: PC 2024.3, PE 6.8. This operation is asynchronous and returns a PrismTask reference. The v4.3 reference documents this action as unconditional (no If-Match needed), but some Prism Central versions reject the request with MISSING_ETAG_HEADER unless an If-Match is supplied. This function always sends one, fetched automatically when -ETag is not provided. .PARAMETER PrismSession The server/FQDN of the PrismSession to use. May be omitted when only one session exists. .PARAMETER VmExtId The globally unique identifier (UUID) of the VM to associate the Category/ies with. .PARAMETER CategoryExtId One or more Category external identifiers (UUID) to associate with the VM (1-256 per call). .PARAMETER VM A PrismVM object, supplied explicitly or through the pipeline. Uses its ExtId and originating session unless -PrismSession is specified. .PARAMETER Category One or more PrismCategory objects instead of -CategoryExtId, supplied explicitly or through the pipeline. Each must have an ExtId and belong to the same Prism session as the target VM. .PARAMETER ETag The current ETag of the VM. When omitted it is retrieved automatically. .EXAMPLE Add-PrismVMCategory -VmExtId 'ba8da8d6-4ee5-440d-8703-206051443ccc' -CategoryExtId '6e3e5679-b356-42fb-b2f7-1601a61656c8' .EXAMPLE Add-PrismVMCategory -VmExtId $vmId -CategoryExtId $envCategoryId, $tierCategoryId .OUTPUTS A PrismTask reference describing the asynchronous association task. #> [CmdletBinding(SupportsShouldProcess = $true, DefaultParameterSetName = 'ByVM')] [OutputType([PrismTask])] param( [Parameter(Mandatory = $false, HelpMessage = 'Prism Session Name')][string]$PrismSession, [Parameter(Mandatory = $true, ParameterSetName = 'ByIdCategory', ValueFromPipelineByPropertyName = $true)] [Parameter(Mandatory = $true, ParameterSetName = 'ById', ValueFromPipelineByPropertyName = $true, HelpMessage = 'VM external identifier (UUID)')] [Alias('Id', 'ExtId')][ValidateNotNullOrEmpty()][string]$VmExtId, [Parameter(Mandatory = $true, ParameterSetName = 'ByVMCategory', ValueFromPipeline = $true)] [Parameter(Mandatory = $true, ParameterSetName = 'ByVM', ValueFromPipeline = $true)] [ValidateNotNull()][PrismVM]$VM, [Parameter(Mandatory = $true, ParameterSetName = 'ById')] [Parameter(Mandatory = $true, ParameterSetName = 'ByVM', HelpMessage = 'Category external identifier(s) (UUID) to associate')] [ValidateCount(1, 256)][string[]]$CategoryExtId, [Parameter(Mandatory = $true, ParameterSetName = 'ByIdCategory', ValueFromPipeline = $true)] [Parameter(Mandatory = $true, ParameterSetName = 'ByVMCategory', ValueFromPipeline = $true)] [ValidateNotNull()][ValidateCount(1, 256)][PrismCategory[]]$Category, [Parameter(Mandatory = $false)][string]$ETag ) process { $categoryIds = if ($PSCmdlet.ParameterSetName -like '*Category') { @($Category.ExtId) } else { $CategoryExtId } if (@($categoryIds | Where-Object { [string]::IsNullOrWhiteSpace($_) }).Count) { throw 'Each Category must have an ExtId.' } $categorySessions = @($Category.PrismSession | Where-Object { $_ } | Select-Object -Unique) $vmId = if ($PSCmdlet.ParameterSetName -like 'ByVM*') { $VM.ExtId } else { $VmExtId } if ([string]::IsNullOrWhiteSpace($vmId)) { throw 'A VM ExtId is required.' } $sessionName = if ($PSCmdlet.ParameterSetName -like 'ByVM*' -and -not $PSBoundParameters.ContainsKey('PrismSession')) { $VM.PrismSession } else { $PrismSession } if (-not $sessionName -and -not $PSBoundParameters.ContainsKey('PrismSession') -and $categorySessions.Count -eq 1) { $sessionName = $categorySessions[0] } $target = "Associate Categories [$($categoryIds -join ', ')]" if (-not $PSCmdlet.ShouldProcess($vmId, $target)) { return } $PrismSessionConfig = Get-PrismSession $sessionName if (@($categorySessions | Where-Object { $_ -ne $PrismSessionConfig.Name }).Count) { throw 'Category and VM must belong to the same Prism session.' } $vmPath = 'vmm/v{0}/ahv/config/vms/{1}' -f $PrismSessionConfig.ApiVersion, $vmId $requestETag = $ETag if (-not $requestETag) { $requestETag = Get-PrismResourceEtag -PrismSession $PrismSessionConfig.Name -Path $vmPath } $body = @{ categories = @($categoryIds | ForEach-Object { @{ extId = $_ } }) } $headers = @{ 'If-Match' = $requestETag 'NTNX-Request-Id' = (New-Guid).Guid } $RequestSplat = @{ PrismSession = $PrismSessionConfig.Name Method = 'POST' Path = ('{0}/$actions/associate-categories' -f $vmPath) Header = $headers Body = $body } $Response = Invoke-PrismRequest @RequestSplat return [PrismTask]::new($Response.data, $PrismSessionConfig.Name) } } |