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