Public/Get-PrismCategory.ps1
|
function Get-PrismCategory { <# .SYNOPSIS Lists Categories, or gets the details of a single Category. .DESCRIPTION With no -ExtId, lists all Categories defined on the system using the v4 "List categories" endpoint, supporting OData paging/filtering/ordering/selection. With -ExtId, retrieves the details of a single Category using the "Get category" endpoint. List results return PrismCategory objects directly, without an API envelope. Name is a writable alias of Key. With -ExtId or -Category, returns one PrismCategory. Each object's RawData property retains its original category payload. Use -Verbose to display category and page totals for list requests. .NOTES Implements: GET /prism/v{ApiVersion}/config/categories (operationId: listCategories) GET /prism/v{ApiVersion}/config/categories/{extId} (operationId: getCategoryById) Path/schema confirmed against the official Nutanix v4.4 API reference (namespace 'prism'). Uses the selected session's ApiVersion for both endpoints. To find the Categories currently assigned to a VM, use Get-PrismVM and inspect the returned PrismVM object's .Categories array (a list of CategoryReference objects), or pass an OData -Filter such as "categories/any(c:c/extId eq '<CategoryExtId>')" to Get-PrismVM. .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 retrieve. .PARAMETER Category A PrismCategory to refresh, supplied explicitly or through the pipeline. Uses its ExtId and session unless -PrismSession is specified. .PARAMETER Key A single category key to match case-sensitively. Name is an alias. Combined with Value and any additional Filter using AND. The existing Page and Limit parameters still apply. .PARAMETER Value A single category value to match case-sensitively. With Key, finds the specific key/value pair; alone, matches the value across all keys. For case-insensitive matching, use -Filter with tolower instead. .PARAMETER Page Zero-based page number of the result set (default 0), matching the API's $page parameter and pagination links in metadata. .PARAMETER Limit ($limit) Maximum number of records to return (1-100, default 50). .PARAMETER Filter ($filter) An OData filter expression, e.g. "key eq 'Environment'". .PARAMETER OrderBy ($orderby) An OData order-by expression, e.g. "key asc". .PARAMETER Select ($select) An OData select expression listing the properties to return. .EXAMPLE Get-PrismCategory .EXAMPLE Get-PrismCategory -Filter "key eq 'Environment'" .EXAMPLE Get-PrismCategory -Key 'Environment' -Value 'Production' .EXAMPLE Get-PrismCategory -Value 'Production' .EXAMPLE Get-PrismCategory -Filter "tolower(key) eq 'environment' and tolower(value) eq 'production'" Matches key and value without case sensitivity using an OData filter. .EXAMPLE $categories = @(Get-PrismCategory -Page 0 -Limit 100 -Verbose) $categories .EXAMPLE (Get-PrismCategory -ExtId '6e3e5679-b356-42fb-b2f7-1601a61656c8').RawData .OUTPUTS PrismCategory objects for lists, or one PrismCategory with -ExtId or -Category. RawData contains the original category payload without API metadata. #> [CmdletBinding(DefaultParameterSetName = 'List')] [OutputType([PrismCategory])] param( [Parameter(Mandatory = $false, HelpMessage = 'Prism Session Name')][string]$PrismSession, [Parameter(Mandatory = $true, ParameterSetName = 'ById', ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = 'Category external identifier (UUID)')] [Alias('Id', 'CategoryExtId')][ValidateNotNullOrEmpty()][string]$ExtId, [Parameter(Mandatory = $true, ParameterSetName = 'ByCategory', ValueFromPipeline = $true)] [ValidateNotNull()][PrismCategory]$Category, [Parameter(ParameterSetName = 'List')] [Alias('Name')][ValidateNotNullOrEmpty()][string]$Key, [Parameter(ParameterSetName = 'List')] [ValidateNotNullOrEmpty()][string]$Value, [Parameter(ParameterSetName = 'List')][ValidateRange(0, [int]::MaxValue)][int]$Page = 0, [Parameter(ParameterSetName = 'List')][ValidateRange(1, 100)][int]$Limit = 50, [Parameter(ParameterSetName = 'List')][string]$Filter, [Parameter(ParameterSetName = 'List')][string]$OrderBy, [Parameter(ParameterSetName = 'List')][string]$Select ) process { $categoryId = if ($PSCmdlet.ParameterSetName -eq 'ByCategory') { $Category.ExtId } else { $ExtId } if ($PSCmdlet.ParameterSetName -ne 'List' -and [string]::IsNullOrWhiteSpace($categoryId)) { throw 'A Category ExtId is required.' } $sessionName = if ($PSCmdlet.ParameterSetName -eq 'ByCategory' -and -not $PSBoundParameters.ContainsKey('PrismSession')) { $Category.PrismSession } else { $PrismSession } $PrismSessionConfig = Get-PrismSession $sessionName $categoryPath = 'prism/v{0}/config/categories' -f $PrismSessionConfig.ApiVersion if ($PSCmdlet.ParameterSetName -ne 'List') { $RequestSplat = @{ PrismSession = $PrismSessionConfig.Name Method = 'GET' Path = ('{0}/{1}' -f $categoryPath, $categoryId) } $response = Invoke-PrismRequest @RequestSplat return [PrismCategory]::new($response.data, $PrismSessionConfig.Name) } $effectiveFilter = $Filter $filterParts = @() if ($PSBoundParameters.ContainsKey('Key')) { $filterParts += "key eq '{0}'" -f $Key.Replace("'", "''") } if ($PSBoundParameters.ContainsKey('Value')) { $filterParts += "value eq '{0}'" -f $Value.Replace("'", "''") } if ($filterParts.Count) { if (-not [string]::IsNullOrWhiteSpace($Filter)) { $filterParts += $Filter } $effectiveFilter = if ($filterParts.Count -eq 1) { $filterParts[0] } else { ($filterParts | ForEach-Object { '({0})' -f $_ }) -join ' and ' } } $query = @{ '$page' = $Page '$limit' = $Limit '$filter' = $effectiveFilter '$orderby' = $OrderBy '$select' = $Select } $RequestSplat = @{ PrismSession = $PrismSessionConfig.Name Method = 'GET' Path = $categoryPath Query = $query } $response = Invoke-PrismRequest @RequestSplat $totalCategories = $response.metadata.totalAvailableResults if ($null -ne $totalCategories) { $totalPages = [math]::Ceiling($totalCategories / $Limit) Write-Verbose "$totalCategories categories across $totalPages pages. Requested page $Page (up to $Limit categories per page)." } else { Write-Verbose "Requested page $Page (up to $Limit categories per page). The API did not provide category/page totals." } foreach ($categoryData in $response.data) { [PrismCategory]::new($categoryData, $PrismSessionConfig.Name) } } } |