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. RawData retains the original category payload. .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. .EXAMPLE $spec = @{ key = 'Environment' value = 'Production' description = 'Production workloads' } New-PrismCategory -Category $spec .EXAMPLE New-PrismCategory -Name 'Environment' -Value 'Production' .OUTPUTS A PrismCategory with its original category payload in RawData. #> [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 ) 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 return [PrismCategory]::new($response.data, $PrismSessionConfig.Name) } } |