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. Use -Raw to get the untouched API response with complete category objects. 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 One or more category keys to match without case sensitivity, returning their key/value pairs with the original casing preserved. Name is an alias. Multiple keys are combined with OR; an additional Filter is combined with AND. The existing Page and Limit parameters still apply. For case-sensitive matching, use -Filter instead, for example -Filter "key eq 'AppType'". .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. .PARAMETER Raw Returns the full API response (envelope plus the complete Category object(s), including metadata) instead of typed PrismCategory output. .EXAMPLE Get-PrismCategory .EXAMPLE Get-PrismCategory -Filter "key eq 'Environment'" .EXAMPLE Get-PrismCategory -Key 'Environment', 'Application' .EXAMPLE $categories = @(Get-PrismCategory -Page 0 -Limit 100 -Verbose) $categories .EXAMPLE Get-PrismCategory -ExtId '6e3e5679-b356-42fb-b2f7-1601a61656c8' -Raw .OUTPUTS PrismCategory objects for lists, or one PrismCategory with -ExtId or -Category. With -Raw, the full API response, including 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')][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, [Parameter(Mandatory = $false)][switch]$Raw ) 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 if ($Raw.IsPresent) { return $response } return [PrismCategory]::new($response.data, $PrismSessionConfig.Name) } $effectiveFilter = $Filter if ($PSBoundParameters.ContainsKey('Key')) { $keyFilters = foreach ($categoryKey in $Key) { "tolower(key) eq '{0}'" -f $categoryKey.ToLowerInvariant().Replace("'", "''") } $keyFilter = $keyFilters -join ' or ' $effectiveFilter = if ([string]::IsNullOrWhiteSpace($Filter)) { $keyFilter } else { '({0}) and ({1})' -f $keyFilter, $Filter } } $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." } if ($Raw.IsPresent) { return $response } foreach ($categoryData in $response.data) { [PrismCategory]::new($categoryData, $PrismSessionConfig.Name) } } } |