Public/Get-DuneUser.ps1
|
<#
.SYNOPSIS Retrieve Dune user(s). .DESCRIPTION Returns one or more `DuneUser` objects from the authentication service. You can fetch a single user by `Id` or filter by `FirstName`, `LastName` or `Email`. Use `-Raw` to return the raw API objects and `-IncludeDeleted` to include soft-deleted users. .PARAMETER Id The numeric Id of the user to retrieve. Use the `Id` parameter set to return a single user. .PARAMETER FirstName Filter users by first name (supports wildcard matching). .PARAMETER LastName Filter users by last name (supports wildcard matching). .PARAMETER Email Filter users by email address (supports wildcard matching). .PARAMETER Raw Switch to return the raw JSON objects from the API instead of `DuneUser` class objects. .PARAMETER IncludeDeleted Include soft-deleted users in the results. .PARAMETER CreatedAfter Only return users created after the given date/time (server-side filter, `CreatedDate > CreatedAfter`). Local times are converted to UTC. .PARAMETER CreatedBefore Only return users created before the given date/time (server-side filter, `CreatedDate < CreatedBefore`). Local times are converted to UTC. .EXAMPLE PS> Get-DuneUser -Id 123 Returns the `DuneUser` with Id 123. .EXAMPLE PS> Get-DuneUser -FirstName "John" -Email "*@yendico.ch" Returns users whose first name is like 'John' and whose email matches the pattern. .EXAMPLE PS> Get-DuneUser -Id 123 -Raw Returns the raw API response for the specified user. #> function Get-DuneUser { [CmdletBinding(DefaultParameterSetName = "Default")] param ( [Parameter(ParameterSetName = "Id")] [int]$Id, [Parameter(ParameterSetName = "StringFilters")] [string]$FirstName, [Parameter(ParameterSetName = "StringFilters")] [string]$LastName, [Parameter(ParameterSetName = "StringFilters")] [string]$Email, [Parameter()] [datetime]$CreatedAfter, [Parameter()] [datetime]$CreatedBefore, [Parameter()] [switch]$Raw, [Parameter()] [switch]$IncludeDeleted ) begin { Write-Debug "$($MyInvocation.MyCommand)|begin" $ReturnObjects = @() $ProcessedUrls = @() $BaseUri = "authentication/users" $Method = "GET" } process { Write-Debug "$($MyInvocation.MyCommand)|process|$($PSCmdlet.ParameterSetName)" # Build Uri $Uri = switch ($PSCmdlet.ParameterSetName) { 'Id' { '{0}?Id={1}' -f $BaseUri, $Id } Default { $BaseUri } } if ($FirstName) { $Uri = $Uri | Add-UriQueryParam "FirstNameILike=$FirstName" -ConvertWildcards } if ($LastName) { $Uri = $Uri | Add-UriQueryParam "LastNameILike=$LastName" -ConvertWildcards } if ($Email) { $Uri = $Uri | Add-UriQueryParam "EmailILike=$Email" -ConvertWildcards } if ($IncludeDeleted) { $Uri = $Uri | Add-UriQueryParam "IncludeDeleted=1" } if ($PSBoundParameters.ContainsKey('CreatedAfter')) { $Uri = $Uri | Add-UriQueryParam "CreatedDateGreaterThan=$([uri]::EscapeDataString($CreatedAfter.ToUniversalTime().ToString('o')))" } if ($PSBoundParameters.ContainsKey('CreatedBefore')) { $Uri = $Uri | Add-UriQueryParam "CreatedDateLessThan=$([uri]::EscapeDataString($CreatedBefore.ToUniversalTime().ToString('o')))" } # ApiCall and Object conversion if ($ProcessedUrls -notcontains $Uri) { try { $ResultItems = Invoke-DuneApiRequest -Uri $Uri -Method $Method -ExtractItems $ReturnObjects += $ResultItems | ForEach-Object { if ($Raw) { $_ } else { ConvertTo-DuneClassObject -Class DuneUser -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 } } |