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