Public/Get-iPilotTeamsUser.ps1
Function Get-iPilotTeamsUser { <# .Synopsis Displays iPilot user(s) .Description Returns iPilot users in iPilot domain with optional filters. .Parameter FilterByFirstName Filter results by user's First Name. .Parameter FilterByLastName Filter results by user's Last Name. .Parameter FilterByTelephoneNumber Filter results by TelephoneNumber (10-digits or less for a partial match). .Parameter FilterByUserPrincipalName Filter results by user's User Principal Name. .Parameter FilterByNote Filter results by user's iPilot Note field value. .Parameter FilterByStatus Filter results by iPilot status. .Parameter ApiVersion Version of the iPilot to use. Defaults to v1. .Parameter iPilotDomain iPilot Domain Name. .Parameter NumberOfRecords Number of records returned by API (limit 100) .Example # Get avilable numbers with the status set to Configured using API Version v1 in the contoso.com iPilot domain Get-iPilotTeamsUser -FilterByStatus Configured -iPilotDomain contoso.com .Example # Get avilable numbers with the Sales Note in the contoso.com iPilot domain with Verbose output Get-iPilotTeamsUser -FilterByNote -Note "Sales" -iPilotDomain contoso.com -Verbose #> Param ( [System.String] $FilterByUserPrincipalName, [ValidateSet("All","Assigned","Configured","Configured-AA","FailedToAssign","FailedToGrantPolicy","FailedToUnassign","InvalidUPN","NotConfigured","PendingAssign","PendingStopped","PendingStopped-AA","PendingUnassign","Queued","Queued-AA","Stopped","Stopped-AA","Unassigned","Unassigned-AA")] [System.String] $FilterByStatus = "All", [System.String] $FilterByFirstName, [System.String] $FilterByLastName, [System.Int64] [ValidatePattern('\d{5,15}$')] [Parameter(Mandatory = $false, HelpMessage = 'Provide telephone number in E.164 format without the + character. Ex. 12223334444')] $FilterByTelephoneNumber, [System.String] $ApiUrl = "https://api.nuwave.com", [System.String] $ApiKey, [System.String] $ApiVersion = "v1", [System.String] $iPilotDomain, [System.Int16] $NumberOfRecords = [System.Int16]::MaxValue, [System.Management.Automation.PSCredential] $Credential ) Begin { # UserPrincipalName validation if ($FilterByUserPrincipalName -and $FilterByUserPrincipalName -notlike "*@*.*") { throw "Check the formatting of the user's User Principal Name. Format should be jdoe@contoso.com" } # Set iPilot Domain if (!$global:IP_iPilotDomain -and !$iPilotDomain) { throw "Run Get-iPilotTeamsDomain or provide domain using -iPilotDomain" } elseif (!$iPilotDomain) { $iPilotDomain = $global:IP_iPilotDomain Write-Verbose "iPilot Domain: $iPilotDomain" } # else use passed in iPilotDomain } Process { # Verbose Switch if($PSBoundParameters.containskey("Verbose")) { $PreviousVerbosePreference = $VerbosePreference $VerbosePreference = "continue" } # Debug Switch if($PSBoundParameters.containskey("Debug")) { $PreviousDebugPreference = $DebugPreference $DebugPreference = "continue" } # Get/re-use OAuth Token $InitializeiPilotSessionSplat = @{ ApiUrl = $ApiUrl ApiVersion = $ApiVersion ApiKey = $ApiKey Credential = $Credential } if ($global:IP_Instance) { $InitializeiPilotSessionSplat += @{ Instance = $global:IP_Instance } } if ($VerbosePreference -eq "Continue") { $InitializeiPilotSessionSplat += @{ Verbose = $true } } if ($DebugPreference -eq "Continue") { $InitializeiPilotSessionSplat += @{ Debug = $true } } Initialize-iPilotSession @InitializeiPilotSessionSplat # Build iPilot API Request $GetiPilotUsersRequestUri = "$ApiUrl/$ApiVersion/msteams/$iPilotDomain/users?limit=$NumberOfRecords&page=1" if ($global:IP_Instance) { $GetiPilotUsersRequestUri += "&instance=$global:IP_Instance" } Write-Verbose "GetiPilotUsersRequestUri: $GetiPilotUsersRequestUri" #region Add each filter to the Uri $Filter = $NULL Add-Type -AssemblyName System.Web # First Name if ($FilterByFirstName) { $FilterByFirstName = [System.Web.HttpUtility]::UrlPathEncode($FilterByFirstName) Write-Verbose "Filtering by Status set to $FilterByFirstName" $Filter += "&firstname=$FilterByFirstName" } # Last Name if ($FilterByLastName) { $FilterByLastName = [System.Web.HttpUtility]::UrlPathEncode($FilterByLastName) Write-Verbose "Filtering by Last Name set to $FilterByLastName" $Filter += "&lastname=$FilterByLastName" } # TelephoneNumber if ($FilterByTelephoneNumber) { Write-Verbose "Filtering by telephone number containing: $FilterByTelephoneNumber" $Filter += "&telephoneNumber=$FilterByTelephoneNumber" } # UserPrincipalName if ($FilterByUserPrincipalName) { $FilterByUserPrincipalNameEndcoded = [System.Web.HttpUtility]::UrlPathEncode($FilterByUserPrincipalName) Write-Verbose "Filtering by UserPrincipalName: $FilterByUserPrincipalNameEndcoded (Unencoded: $FilterByUserPrincipalName)" $Filter += "&upn=$FilterByUserPrincipalNameEndcoded" } # Note if ($FilterByNote) { $FilterByNote = [System.Web.HttpUtility]::UrlPathEncode($FilterByNote) Write-Verbose "Filtering by Note set to $FilterByNote" $Filter += "¬e=$FilterByNote" } # Status if ($FilterByStatus) { # Convert status to API value $FilterByStatusEncoded = switch ($FilterByStatus) { All {"ALL"} Assigned {"ASSIGNED"} Configured {"CONFIGURED"} Configured-AA {"CONFIGURED TO AA & CQ"} FailedToAssign {"FAILED_TO_ASSIGN"} FailedToGrantPolicy {"FAILED_TO_GRANT_POLICY"} FailedToUnassign {"FAILED_TO_UNASSIGN"} InvalidUPN {"INVALID_UPN"} NotConfigured {"NOT_CONFIGURED"} #Pending {"PENDING"} PendingAssign {"PENDING_ASSIGN"} PendingStopped {"PENDING_STOPPED"} PendingStopped-AA {"PENDING_STOPPED-AA"} PendingUnassign {"PENDING_UNASSIGN"} Queued {"QUEUED"} Queued-AA {"QUEUED-AA"} Stopped {"STOPPED"} Stopped-AA {"STOPPED-AA"} Unassigned {"UNASSIGNED"} Unassigned-AA {"UNASSIGNED-AA"} } # All status filter if ($FilterByStatusEncoded -eq "ALL") { Write-Verbose "All status filter specified, using no status filter" } else { Write-Verbose "Filtering by Status set to $FilterByStatusEncoded (Unencoded: $FilterByStatus)" $Filter += "&status=$FilterByStatusEncoded" } } #endregion Add each filter to the Uri # Splat Invoke-RestMethod parameters $RequestURI = $GetiPilotUsersRequestUri + $Filter Write-Verbose "Request Uri: $RequestURI" Write-Verbose "Request Method: Get" $GetiPilotUsersInvokeParams = @{ Uri = $RequestURI Method = "Get" ContentType = "application/json" Headers = @{ "X-Access-Token" = $global:IP_iPilotOAuthToken.access_token "x-api-key" = $global:IP_iPilotApiKey } } # Execute the REST API Try { $GetiPilotUsersResponse = Invoke-RestMethod @GetiPilotUsersInvokeParams -ErrorAction Stop } Catch { Write-Error "Failed to retreive iPilot User(s)`nStatus: $($GetiPilotUsersResponse.status)`nURL: $($GetiPilotUsersRequestUri). Error: $($_)" break } # Return Available Numbers if ($GetiPilotUsersResponse.id.Count -ge 1) { Write-Debug "GetiPilotUsersResponse:`n$($GetiPilotUsersResponse | Out-String)" # Change output to PascalCase $Users = $GetiPilotUsersResponse | Select-Object @{Name = 'Id' ; Expression = {$_.id}}, @{Name = 'UserPrincipalName' ; Expression = {$_.upn}}, @{Name = 'FirstName' ; Expression = {$_.firstName}}, @{Name = 'LastName' ; Expression = {$_.lastName}}, @{Name = 'Note' ; Expression = {$_.note}}, @{Name = 'Status' ; Expression = {$_.status}}, @{Name = 'TelephoneNumber' ; Expression = {$_.telephoneNumber}} return $Users } else { Write-Error "No users found using the specified filters." } # Verbose Switch if($PSBoundParameters.containskey("Verbose")) { $VerbosePreference = $PreviousVerbosePreference } # Debug Switch if($PSBoundParameters.containskey("Debug")) { $DebugPreference = $PreviousDebugPreference } } } |