Dune

1.0.2

Public/Get-DuneJob.ps1

<#
.SYNOPSIS
Retrieve jobs.

.DESCRIPTION
Gets job objects and supports multiple parameter sets to filter by id, deployment, resource group, resource, job event, and type. You can also filter by job name, job type, and state. Returns `DuneJob` objects by default; use `-Raw` for raw API output.

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

.PARAMETER Id
The GUID of a job. Use the `Id` parameter set for a specific job.

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

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

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

.PARAMETER JobEvent
A `DuneJobEvent` object; returns the job related to the supplied job event (pipeline input supported).

.PARAMETER Type
When using `ByType`, specify `Deployment`, `ResourceGroup`, or `Resource` to filter by config item type.

.PARAMETER JobType
Filter by `JobTypes` enum.

.PARAMETER State
Filter by `JobStates` enum.

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

.PARAMETER IncludeDeleted
Include deleted jobs in results.

.EXAMPLE
PS> Get-DuneJob -Name "daily-backup"
Returns jobs with names matching `daily-backup`.

.EXAMPLE
PS> Get-DuneJob -Id 3d8f6b5a-...
Returns the job with the specified `Id`.

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

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

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

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

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

        [Parameter(ParameterSetName = "JobEvent", ValueFromPipeline)]
        [DuneJobEvent]$JobEvent,

        [Parameter(ParameterSetName = "ByType")]
        [ValidateSet('Deployment', 'ResourceGroup', 'Resource')]
        [string]$Type,

        [Parameter()]
        [JobTypes]$JobType,

        [Parameter()]
        [JobStates]$State,

        [Parameter()]
        [switch]$Raw,

        [Parameter()]
        [switch]$IncludeDeleted
    )

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

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

        # Build Uri
        $Uri = switch ($PSCmdlet.ParameterSetName) {
            'Id' { '{0}/{1}' -f $BaseUri, $Id }
            'Deployment' { '{0}?ConfigItemId={1}&ConfigItemType=Deployment' -f $BaseUri, $Deployment.Id }
            'ResourceGroup' { '{0}?ConfigItemId={1}&ConfigItemType=ResourceGroup' -f $BaseUri, $ResourceGroup.Id }
            'Resource' { '{0}?ConfigItemId={1}&ConfigItemType={2}' -f $BaseUri, $Resource.Id, $Resource.ObjectType }
            'JobEvent' { '{0}/{1}' -f $BaseUri, $JobEvent.JobId }
            'ByType' { '{0}?ConfigItemType={1}' -f $BaseUri, $Type }
            Default { $BaseUri }
        }
        if ($PSBoundParameters.ContainsKey('Name')) {
            $Uri = $Uri | Add-UriQueryParam "NameILike=$Name" -ConvertWildcards
        }
        if ($PSBoundParameters.ContainsKey('JobType')) {
            $Uri = $Uri | Add-UriQueryParam "JobType=$JobType"
        }
        if ($PSBoundParameters.ContainsKey('State')) {
            $Uri = $Uri | Add-UriQueryParam "State=$State"
        }
        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 DuneJob -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 | Sort-Object -Unique * | Sort-Object StartTime
    }
}