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