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 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 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. .PARAMETER ETag The current ETag of the VM. When omitted it is retrieved automatically. .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, [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 = "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 = $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/disassociate-categories' -f $vmPath) Header = $headers Body = $body } $Response = Invoke-PrismRequest @RequestSplat return [PrismTask]::new($Response.data, $PrismSessionConfig.Name) } } |