iPilot

1.0.4

Public/Get-iPilotCarrier.ps1

Function Get-iPilotCarrier {
    <#
        .Synopsis
        Displays iPilot user(s)

        .Description
        Returns iPilot Carrier in iPilot domain with optional filters.

        .Parameter CarrierName
        Filter results by user's First Name.

        .Parameter ApiVersion
        Version of the NuWave 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-iPilotCarrier -NumberOfRecords 10 -iPilotDomain contoso.com

        .Example
        # Get carrier named "Contoso" in the contoso.com iPilot domain with Verbose output
        Get-iPilotCarrier -CarrierName "Contoso" -iPilotDomain contoso.com -Verbose
    #>
    Param (
        [Parameter(
            Mandatory = $false,
            ValueFromPipeline = $true,
            HelpMessage = 'Allowed characters: Alphanumeric, spaces, and hyphens')]
            [ValidatePattern('^[a-zA-Z0-9 ]+$')]
            [System.String] $CarrierName,
        [System.String]
            $ApiUrl = $global:IP_ApiUrl, 
        [System.String]
            $ApiKey = $global:IP_ApiKey, 
        [System.String]
            $ApiVersion = "v1",
        [System.String]
            $iPilotDomain = $global:IP_iPilotDomain,
        [System.Int16]
            $NumberOfRecords = [System.Int16]::MaxValue,
        [System.Management.Automation.PSCredential]
            $Credential
     )

    Begin {

        # 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
        $GetiPilotCarrierRequestUri = "$ApiUrl/$ApiVersion/msteams/$iPilotDomain/carriers?limit=$NumberOfRecords&page=1"
        if ($Instance) {
            $GetiPilotCarrierRequestUri += "&instance=$Instance"
        }
        Write-Verbose "GetiPilotCarrierRequestUri: $GetiPilotCarrierRequestUri"

        # Splat Invoke-RestMethod parameters
        Write-Verbose "Request Method: Get"
        $GetiPilotCarrierInvokeParams = @{
            Uri = $GetiPilotCarrierRequestUri
            Method = "Get"
            ContentType = "application/json"
            Headers = @{
                "X-Access-Token" = $iPilotOAuthToken.access_token
                "x-api-key"      = $iPilotApiKey
            }
        }

        Write-Verbose "GetiPilotCarrierInvokeParams:`n$($GetiPilotCarrierInvokeParams | Format-Table | Out-String)" -Verbose

        # Execute the REST API
        Try {
            $GetiPilotCarrierResponse = Invoke-RestMethod @GetiPilotCarrierInvokeParams -ErrorAction Stop
            Write-Debug "GetiPilotCarrierResponse:`n$GetiPilotCarrierResponse"
        } Catch {
            Write-Error "Failed to retreive iPilot Carrier(s)`nStatus: $($GetiPilotCarrierResponse.status)`nURL: $($GetiPilotCarrierRequestUri). Error: $($_)"
            break
        }

        # Convert response object to array of objects
        $Carriers = @()
        ($GetiPilotCarrierResponse.carriers | Out-String) -split "`r`n" | Where-Object {$_} | ForEach-Object {
            $Carrier = $_.Split(":").TrimStart()
            $Carriers += [pscustomobject]@{'CarrierId'=$Carrier[0];'CarrierName'=$Carrier[1]}
        }
        Write-Debug "Carriers:`n$Carriers"

        # If CarrierName specified, return ID
        if ($CarrierName) {
            $Carriers = $Carriers | Where-Object {$_.CarrierName -eq $CarrierName}
        }

        # Return Carrier Array
        if ($Carriers) {
            return $Carriers
        } else {
            Write-Error "No Carrier found."
        }

        # Verbose Switch
        if($PSBoundParameters.containskey("Verbose")) {
            $VerbosePreference = $PreviousVerbosePreference
        }

        # Debug Switch
        if($PSBoundParameters.containskey("Debug")) {
            $DebugPreference = $PreviousDebugPreference
        }
    }
}