Public/Set-PrismCategory.ps1
|
function Set-PrismCategory { <# .SYNOPSIS Updates a Category. .DESCRIPTION Updates the Category with the given external identifier. This is a conditional operation: the v4 API requires the current ETag of the Category (supplied as an If-Match header). This function first performs a GET to obtain a fresh ETag for each Category. .NOTES Implements: PUT /prism/v{ApiVersion}/config/categories/{extId} (operationId: updateCategoryById) Uses the selected session's ApiVersion for the endpoint. The body must conform to the prism.config.Category schema. .PARAMETER PrismSession The server/FQDN of the PrismSession to use. May be omitted when only one session exists. .PARAMETER ExtId The external identifier (UUID) of the Category to update. When omitted, uses the supplied PrismCategory's ExtId. .PARAMETER Category The updated PrismCategory, supplied explicitly or through the pipeline. Hashtables with matching properties can be converted automatically. Uses its session unless -PrismSession is supplied. Only writable fields are sent. .EXAMPLE $category = Get-PrismCategory -ExtId $id $category.description = 'Updated description' Set-PrismCategory -Category $category .OUTPUTS The updated PrismCategory. #> [CmdletBinding(SupportsShouldProcess = $true)] [OutputType([PrismCategory])] param( [Parameter(Mandatory = $false, HelpMessage = 'Prism Session Name')][string]$PrismSession, [Parameter(Mandatory = $false, HelpMessage = 'Category external identifier (UUID)')] [Alias('Id', 'CategoryExtId')][ValidateNotNullOrEmpty()][string]$ExtId, [Parameter(Mandatory = $true, ValueFromPipeline = $true, HelpMessage = 'Updated Category specification')] [Alias('Body', 'Spec')][ValidateNotNull()][PrismCategory]$Category ) process { $categoryId = if ($PSBoundParameters.ContainsKey('ExtId')) { $ExtId } else { $Category.ExtId } if ([string]::IsNullOrWhiteSpace($categoryId)) { throw 'A Category ExtId is required.' } $body = $Category.ToApiBody() if (-not $PSCmdlet.ShouldProcess($categoryId, 'Update Category')) { return } $sessionName = if (-not $PSBoundParameters.ContainsKey('PrismSession')) { $Category.PrismSession } else { $PrismSession } $PrismSessionConfig = Get-PrismSession $sessionName $categoryPath = 'prism/v{0}/config/categories/{1}' -f $PrismSessionConfig.ApiVersion, $categoryId $requestETag = Get-PrismResourceEtag -PrismSession $PrismSessionConfig.Name -Path $categoryPath $headers = @{ 'If-Match' = $requestETag 'NTNX-Request-Id' = (New-Guid).Guid } $RequestSplat = @{ PrismSession = $PrismSessionConfig.Name Method = 'PUT' Path = $categoryPath Header = $headers Body = $body } $response = Invoke-PrismRequest @RequestSplat return [PrismCategory]::new($response.data, $PrismSessionConfig.Name) } } |