Public/New-PrismCategory.ps1

function New-PrismCategory {
    <#
    .SYNOPSIS
        Creates a Category.
 
    .DESCRIPTION
        Creates a new Category (a key/value pair used to tag and group entities such
        as VMs) from the supplied specification, or from a standalone -Name/-Value
        pair.
 
        Returns a PrismCategory with Key/Value and its ExtId. Name is a writable
        alias of Key. Use -Raw to get the full API response.
 
    .NOTES
        Implements:
          POST /prism/v{ApiVersion}/config/categories (operationId: createCategory)
 
        Uses the selected session's ApiVersion for the endpoint.
 
        The body must conform to the prism.config.Category schema. At minimum 'key'
        and 'value' are required.
 
    .PARAMETER PrismSession
        The server/FQDN of the PrismSession to use. May be omitted when only one session exists.
 
    .PARAMETER Category
        A PrismCategory specification to create. Hashtables with matching properties
        can be converted automatically. Uses its session unless -PrismSession is supplied.
 
    .PARAMETER Name
        The Category key/name to create. Used together with -Value instead of
        -Category.
 
    .PARAMETER Value
        The Category value to create. Used together with -Name instead of -Category.
 
    .PARAMETER Raw
        Returns the full API response instead of a PrismCategory.
 
    .EXAMPLE
        $spec = @{
            key = 'Environment'
            value = 'Production'
            description = 'Production workloads'
        }
        New-PrismCategory -Category $spec
 
    .EXAMPLE
        New-PrismCategory -Name 'Environment' -Value 'Production'
 
    .OUTPUTS
        By default, a PrismCategory. With -Raw, the full API
        response.
    #>


    [CmdletBinding(SupportsShouldProcess = $true, DefaultParameterSetName = 'Spec')]
    [OutputType([PrismCategory])]
    param(
        [Parameter(Mandatory = $false,
            HelpMessage = 'Prism Session Name')][string]$PrismSession,

        [Parameter(Mandatory = $true,
            ParameterSetName = 'Spec',
            ValueFromPipeline = $true,
            HelpMessage = 'Category specification to create')]
        [Alias('Body', 'Spec')][ValidateNotNull()][PrismCategory]$Category,

        [Parameter(Mandatory = $true,
            ParameterSetName = 'Values',
            ValueFromPipelineByPropertyName = $true,
            HelpMessage = 'Category key/name to create')]
        [string]$Name,

        [Parameter(Mandatory = $true,
            ParameterSetName = 'Values',
            ValueFromPipelineByPropertyName = $true,
            HelpMessage = 'Category value to create')]
        [string]$Value,
        [Parameter(Mandatory = $false)][switch]$Raw
    )

    process {
        if ($PSCmdlet.ParameterSetName -eq 'Values') {
            $Category = [PrismCategory]::new($Name, $Value)
        }

        $body = $Category.ToApiBody()
        $displayKey = $Category.key ?? '<unnamed>'
        $displayValue = $Category.value ?? ''
        if (-not $PSCmdlet.ShouldProcess("$displayKey`: $displayValue", 'Create Category')) { return }

        $sessionName = if (-not $PSBoundParameters.ContainsKey('PrismSession')) { $Category.PrismSession } else { $PrismSession }
        $PrismSessionConfig = Get-PrismSession $sessionName

        $headers = @{ 'NTNX-Request-Id' = (New-Guid).Guid }

        $RequestSplat = @{
            PrismSession = $PrismSessionConfig.Name
            Method       = 'POST'
            Path         = ('prism/v{0}/config/categories' -f $PrismSessionConfig.ApiVersion)
            Header       = $headers
            Body         = $body
        }
        $response = Invoke-PrismRequest @RequestSplat

        if ($Raw.IsPresent) { return $response }

        return [PrismCategory]::new($response.data, $PrismSessionConfig.Name)
    }
}