Dune

1.1.3

Public/Get-DuneRole.ps1

<#
.SYNOPSIS
Retrieve Dune roles.
 
.DESCRIPTION
Gets one or more roles from the authorization service. Supports filtering by name, id or the config item type the role applies to. Returns `DuneRole` objects by default; use `-Raw` for raw API responses.
 
.PARAMETER Name
Filter roles by name (supports wildcards). Position 0 in the default parameter set.
 
.PARAMETER Id
The GUID of a role. Use the `Id` parameter set for a single role.
 
.PARAMETER AppliesTo
Filter roles by the type of config item they can be granted on (`Tenant`, `Collection`, `Deployment`, `ResourceGroup`, `Resource`).
 
.PARAMETER Raw
If set, returns raw API objects instead of `DuneRole` objects.
 
.EXAMPLE
PS> Get-DuneRole
Returns all roles of the current tenant.
 
.EXAMPLE
PS> Get-DuneRole -Name "Owner"
Returns all roles named `Owner` (one per config item type).
 
.EXAMPLE
PS> Get-DuneRole -AppliesTo Deployment
Returns the roles that can be granted on deployments.
#>
function Get-DuneRole {
    [CmdletBinding(DefaultParameterSetName = 'Name')]
    param(
        [Parameter(Position=0,ParameterSetName='Name')]
        [string]$Name,

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

        # [Parameter(ParameterSetName='AppliesTo')]
        [ValidateSet('Tenant','Collection','Deployment','ResourceGroup','Resource')]
        [string]$AppliesTo,

        [Parameter()]
        [switch]$Raw
    )

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

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

        $Uri = switch ($PSCmdlet.ParameterSetName) {
            'Id' { "{0}/{1}" -f $BaseUri, $Id }
            Default { $BaseUri }
        }

        if ($PSBoundParameters.ContainsKey('Name') -and $Name) { $Uri = $Uri | Add-UriQueryParam "NameILike=$Name" -ConvertWildcards }
        if ($AppliesTo) { $Uri = $Uri | Add-UriQueryParam "AppliesTo=$($AppliesTo)" }

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

    end { return $ReturnObjects }
}