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)
        }
    }
}