Dune

1.0.2

Public/Get-DuneGenericResource.ps1

<#
.SYNOPSIS
Retrieve generic resources.

.DESCRIPTION
Gets generic resources and supports multiple parameter sets to find resources by `Id`, `ExtId`, `Collection`, `Deployment`, `ResourceGroup`, `Resource`, or `ResourceProvider`. You can filter by `Name` and `DisplayName`, return raw API output with `-Raw`, and include deleted objects.

.PARAMETER Name
Filter resources by name (supports wildcards). Position 0 in the default parameter set.

.PARAMETER Id
The GUID of a generic resource. Use the `Id` parameter set to retrieve a specific resource.

.PARAMETER Collection
A `DuneCollection` object; returns resources in the supplied collection (pipeline input supported).

.PARAMETER Deployment
A `DuneDeployment` object; returns resources for the supplied deployment (pipeline input supported).

.PARAMETER ResourceGroup
A `DuneResourceGroup` object; returns resources in the supplied resource group (pipeline input supported).

.PARAMETER Resource
A `DuneResource` object; returns the resource for the supplied resource (pipeline input supported).

.PARAMETER ResourceProvider
A `DuneResourceProvider` object; filter by resource provider (pipeline input supported).

.PARAMETER ExtId
Filter by external identifier.

.PARAMETER DisplayName
Filter by display name (supports wildcards).

.PARAMETER Raw
If set, returns raw API objects instead of `DuneGenericResource` objects.

.PARAMETER IncludeDeleted
Include deleted resources in results.

.EXAMPLE
PS> Get-DuneGenericResource -Name "app*"
Return generic resources with names matching `app*`.

.EXAMPLE
PS> Get-DuneGenericResource -Id 3d8f6b5a-...
Return the generic resource with the specified `Id`.

.EXAMPLE
PS> Get-DuneCollection -Name "prod" | Get-DuneGenericResource
Pipeline example using the `Collection` parameter set.
#>
function Get-DuneGenericResource {
    [CmdletBinding(DefaultParameterSetName = "Default")]
    param (
        [Parameter(Position = 0)]
        [string]$Name,

        [Parameter(ParameterSetName = "Id")]
        [guid]$Id,

        [Parameter(ParameterSetName = "Collection", ValueFromPipeline)]
        [DuneCollection]$Collection,

        [Parameter(ParameterSetName = "Deployment", ValueFromPipeline)]
        [DuneDeployment]$Deployment,

        [Parameter(ParameterSetName = "ResourceGroup", ValueFromPipeline)]
        [DuneResourceGroup]$ResourceGroup,

        [Parameter(ParameterSetName = "Resource", ValueFromPipeline)]
        [DuneResource]$Resource,

        [Parameter(ParameterSetName = "ResourceProvider", ValueFromPipeline)]
        [DuneResourceProvider]$ResourceProvider,

        [Parameter(ParameterSetName = "ExtId")]
        [string]$ExtId,

        [Parameter()]
        [string]$ExtType,

        [Parameter()]
        [string]$DisplayName,

        [Parameter()]
        [switch]$Raw,

        [Parameter()]
        [switch]$IncludeDeleted
    )

    begin {
        Write-Debug "$($MyInvocation.MyCommand)|begin"
        $ReturnObjects = @()
        $ProcessedUrls = @()
        $BaseUri = 'genericresources'
        $Method = "GET"
    }

    process {
        Write-Debug "$($MyInvocation.MyCommand)|process|$($PSCmdlet.ParameterSetName)"

        # Build Uri
        $Uri = switch ($PSCmdlet.ParameterSetName) {
            'Id' { $BaseUri, $Id -join '/' }
            'ExtId' { '{0}?ExtIdIEquals={1}' -f $BaseUri, $ExtId }
            'Collection' { '{0}?CollectionId={1}' -f $BaseUri, $Collection.Id }
            'Deployment' { $BaseUri, "DeploymentId=$($Deployment.Id)" -join '?' }
            'ResourceGroup' { $BaseUri, "ParentId=$($ResourceGroup.Id)" -join '?' }
            'Resource' {
                if ($Resource.ObjectType -eq 'GenericResource') {
                    $BaseUri, $Resource.Id -join '/'
                }
                else {
                    Write-Warning "Wrong ObjectType $($Resource.ObjectType) for $($Resource.Name) (id: $($Resource.Id))"
                    return
                }
            }
            'ResourceProvider' { $BaseUri, "ResourceProviderId=$($ResourceProvider.Id)" -join '?' }
            Default { $BaseUri }
        }
        if ($Name) {
            $Uri = $Uri | Add-UriQueryParam "NameILike=$Name" -ConvertWildcards
        }
        if ($DisplayName) {
            $Uri = $Uri | Add-UriQueryParam "DisplayNameILike=$DisplayName" -ConvertWildcards
        }
        if ($ExtType) {
            $Uri = $Uri | Add-UriQueryParam "ExtTypeILike=$ExtType" -ConvertWildcards
        }
        if ($IncludeDeleted) {
            $Uri = $Uri | Add-UriQueryParam "IncludeDeleted=1"
        }
        $Uri = $Uri | Add-UriQueryParam "IncludeReferencedObjects=1"

        # ApiCall Cache
        if ($ProcessedUrls -notcontains $Uri) {
            try {
                $ResultItems = Invoke-DuneApiRequest -Uri $Uri -Method $Method -ExtractItems
                $ProcessedUrls += $Uri
                $ReturnObjects += $ResultItems | ForEach-Object {
                    if ($Raw) {
                        $_
                    }
                    else {
                        ConvertTo-DuneClassObject -Class DuneGenericResource -InputObject $_
                    }
                }
            }
            catch {
                throw $_
            }
        }
        else {
            Write-Debug "$($MyInvocation.MyCommand)|process|ApiCall Cache hit: DuneApiRequest for $Uri already invoked"
        }
    }

    end {
        Write-Debug "$($MyInvocation.MyCommand)|end"
        if ($ReturnObjects -and (-not $Raw) -and (-not $ReturnObjects.Deployment)) {
            $Deployments = if (($ReturnObjects.Count -eq 1) -and (-not $ReturnObjects.Deployment)) { $ReturnObjects | Get-DuneDeployment }else { Get-DuneDeployment }
            foreach ($Object in ($ReturnObjects | Where-Object { -not $_.Deployment })) {
                $Object.Deployment = $Deployments | Where-Object Id -EQ $Object.DeploymentId
            }
        }
        return $ReturnObjects | Sort-Object -Unique Id | Sort-Object Name
    }
}