Public/Remove-PrismVMCategory.ps1
|
function Remove-PrismVMCategory { <# .SYNOPSIS Disassociates one or more Categories from a VM. .DESCRIPTION Disassociates the given Category external identifier(s) from the VM using the dedicated "Disassociate categories from a VM" action. .NOTES Implements: POST /vmm/v{ApiVersion}/ahv/config/vms/{extId}/$actions/disassociate-categories (operationId: disassociateCategories) 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 for each VM. .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 disassociate the Category/ies from. .PARAMETER CategoryExtId One or more Category external identifiers (UUID) to disassociate from 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. .EXAMPLE Remove-PrismVMCategory -VmExtId 'ba8da8d6-4ee5-440d-8703-206051443ccc' -CategoryExtId '6e3e5679-b356-42fb-b2f7-1601a61656c8' .OUTPUTS A PrismTask reference describing the asynchronous disassociation 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 disassociate')] [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 ) 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 = "Disassociate 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 = 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/disassociate-categories' -f $vmPath) Header = $headers Body = $body } $Response = Invoke-PrismRequest @RequestSplat return [PrismTask]::new($Response.data, $PrismSessionConfig.Name) } } |