Dune

1.0.2

Public/Get-DuneDisk.ps1

<#
.SYNOPSIS
Retrieve Dune disks.

.DESCRIPTION
Gets disks and supports multiple parameter sets to find disks by `Id`, `ExtId`, `Collection`, `Deployment`, `ResourceGroup`, `Resource`, or `ResourceProvider`. You can also filter by `Name` or `DisplayName` and include deleted objects. Returns `DuneDisk` objects by default; use `-Raw` for raw API results.

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

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

.PARAMETER ExtId
External identifier of a disk. Use the `ExtId` parameter set to filter by external id.

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

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

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

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

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

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

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

.PARAMETER IncludeDeleted
Include deleted disks in results.

.EXAMPLE
PS> Get-DuneDisk -Name "db-data"
Returns disks with names matching `db-data`.

.EXAMPLE
PS> Get-DuneDisk -Id 3d8f6b5a-...
Returns the disk with the specified `Id`.

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

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

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

        [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()]
        [string]$DisplayName,

        [Parameter()]
        [switch]$Raw,

        [Parameter()]
        [switch]$IncludeDeleted
    )

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

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

        # Build Uri
        $Uri = switch ($PSCmdlet.ParameterSetName) {
            'Id' { '{0}?Id={1}' -f $BaseUri, $Id }
            'ExtId' { '{0}?ExtIdIEquals={1}' -f $BaseUri, $ExtId }
            'Resource' { '{0}?ResourceId={1}' -f $BaseUri, $Resource.Id }
            'Collection' { '{0}?CollectionId={1}' -f $BaseUri, $Collection.Id }
            'Deployment' { '{0}?DeploymentId={1}' -f $BaseUri, $Deployment.Id }
            'ResourceGroup' { '{0}?ParentId={1}' -f $BaseUri, $ResourceGroup.Id }
            'ResourceProvider' { '{0}?ResourceProviderId={1}' -f $BaseUri, $ResourceProvider.Id }
            Default { $BaseUri }
        }
        if ($Name) {
            $Uri = $Uri | Add-UriQueryParam "NameILike=$Name" -ConvertWildcards
        }
        if ($DisplayName) {
            $Uri = $Uri | Add-UriQueryParam "DisplayNameILike=$DisplayName" -ConvertWildcards
        }
        if ($IncludeDeleted) {
            $Uri = $Uri | Add-UriQueryParam "IncludeDeleted=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 {
                        If ($_.deployment) { $_.deployment = ConvertTo-DuneClassObject -Class DuneDeployment -InputObject $_.deployment }
                        ConvertTo-DuneClassObject -Class DuneDisk -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) {
            $Deployments = Get-DuneDeployment
            foreach ($Object in $ReturnObjects) {
                $Object.Deployment = $Deployments | Where-Object Id -EQ $Object.DeploymentId
            }
        }
        return $ReturnObjects | Sort-Object -Unique Id | Sort-Object Name
    }
}