Dune

1.0.2

Public/Get-DuneIpAddress.ps1

<#
.SYNOPSIS
Retrieve IP addresses.

.DESCRIPTION
Gets one or more IP addresses from Dune. Supports filtering by address, name, id, external id, subnet, resource id, resource object, IP version, and include-deleted flag. Returns `DuneIpAddress` objects by default; use `-Raw` for raw API output.

.PARAMETER Address
Filter IP addresses by address (supports wildcards). Position 0 in the default parameter set.

.PARAMETER Name
Filter IP addresses by name (supports wildcards).

.PARAMETER Id
The GUID of an IP address. Use the `Id` parameter set to retrieve a specific IP address.

.PARAMETER ExtId
Filter by external identifier.

.PARAMETER Subnet
A `DuneSubnet` object; returns IP addresses for the supplied subnet (pipeline input supported).

.PARAMETER ResourceId
Filter IP addresses by resource GUID.

.PARAMETER Resource
A `DuneResource` object; returns IP addresses assigned to the supplied resource (pipeline input supported).

.PARAMETER Version
IP version to filter by: `v4` or `v6`.

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

.PARAMETER IncludeDeleted
Include deleted IP addresses in results.

.EXAMPLE
PS> Get-DuneIpAddress -Address "10.0.*"
Find IP addresses matching the address pattern.

.EXAMPLE
PS> Get-DuneIpAddress -Id 3d8f6b5a-...
Return the IP address with the specified `Id`.

.EXAMPLE
PS> Get-DuneSubnet -Name "front-end" | Get-DuneIpAddress
Pipeline example using the `Subnet` parameter set.
#>
function Get-DuneIpAddress {
    [CmdletBinding(DefaultParameterSetName = "Default")]
    param (
        [Parameter(Position = 0)]
        [string]$Address,

        [Parameter()]
        [string]$Name,

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

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

        [Parameter(ParameterSetName = "Subnet", ValueFromPipeline)]
        [DuneSubnet]$Subnet,

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

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

        [Parameter()][ValidateSet("v4", "v6")]
        [string]$Version,

        [Parameter()]
        [switch]$Raw,

        [Parameter()]
        [switch]$IncludeDeleted
    )

    begin {
        Write-Debug "$($MyInvocation.MyCommand)|begin"
        $ReturnObjects = @()
        $ProcessedUrls = @()
        $BaseUri = "ipaddresses"
        $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 }
            'Resource' { $BaseUri, "ResourceId=$($Resource.Id)" -join '?' }
            'ResourceId' { $BaseUri, "ResourceId=$($ResourceId)" -join '?' }
            'Subnet' { $BaseUri, "SubnetId=$($Subnet.Id)" -join '?' }
            Default { $BaseUri }
        }
        if ($Name) {
            $Uri = $Uri | Add-UriQueryParam "NameILike=$Name" -ConvertWildcards
        }
        if ($Address) {
            $Uri = $Uri | Add-UriQueryParam "AddressLike=$Address" -ConvertWildcards
        }
        if ($Version) {
            $Uri = $Uri | Add-UriQueryParam "Version=$Version"
        }
        if ($IncludeDeleted) {
            $Uri = $Uri | Add-UriQueryParam "IncludeDeleted=1"
        }

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

    end {
        Write-Debug "$($MyInvocation.MyCommand)|end"
        return $ReturnObjects
    }
}