functions/Get-PpacEnvironment.ps1

<#
    .SYNOPSIS
        Retrieves environments through the Power Platform API.
 
    .DESCRIPTION
        Lists environments by GUID or wildcard through paged discovery.
        Discovery needs the Power Platform Administrator role and a token
        covering that API area, else it warns and yields nothing. See
        Get-BapEnvironment.
 
    .PARAMETER EnvironmentId
        Environment GUID or display name wildcard. GUIDs use a direct request.
 
        Default: *
 
    .PARAMETER AsExcelOutput
        Exports matching environments to an Excel workbook.
 
    .EXAMPLE
        PS C:\> Get-PpacEnvironment
 
        Lists environments accessible to the current identity.
 
    .EXAMPLE
        PS C:\> Get-PpacEnvironment -EnvironmentId "00000000-0000-0000-0000-000000000000"
 
        Retrieves the environment directly by GUID.
        It uses -EnvironmentId to avoid a tenant-wide discovery request.
 
    .EXAMPLE
        PS C:\> Get-PpacEnvironment -EnvironmentId "*Demo*" -AsExcelOutput
 
        Exports environments whose names match the filter.
        It uses -EnvironmentId to filter names.
        It uses -AsExcelOutput to write a workbook.
 
    .NOTES
        Author: d365bap.tools contributors
 
    .LINK
        https://learn.microsoft.com/en-us/rest/api/power-platform/environmentmanagement/environments/list-environments-for-user
 
    .LINK
        https://learn.microsoft.com/en-us/power-platform/admin/programmability-authentication-v2
#>

function Get-PpacEnvironment {
    [CmdletBinding()]
    [OutputType('D365Bap.Tools.PpacEnvironment[]', [object[]])]
    param (
        [Parameter(ValueFromPipelineByPropertyName = $true)]
        [SupportsWildcards()]
        [ValidateNotNullOrEmpty()]
        [string] $EnvironmentId = '*',

        [switch] $AsExcelOutput
    )

    process {
        $objSecureToken = Get-BapAccessToken -PowerPlatform
        $tokenValue = ConvertFrom-SecureString -AsPlainText `
            -SecureString $objSecureToken

        $apiVersion = $script:BapApiVersions.PowerPlatform
        $parsedId = [guid]::Empty
        $isEnvironmentId = [guid]::TryParse($EnvironmentId, [ref]$parsedId)
        $builderName = 'Microsoft.PowerPlatform.Management.Environmentmanagement.Environments.EnvironmentsRequestBuilder'
        $requestUri = 'https://api.powerplatform.com/environmentmanagement/environments?api-version={0}' `
            -f $apiVersion

        if ($isEnvironmentId) {
            $builderName = 'Microsoft.PowerPlatform.Management.Environmentmanagement.Environments.Item.EnvironmentItemRequestBuilder'
            $requestUri = 'https://api.powerplatform.com/environmentmanagement/environments/{0}?api-version={1}' `
                -f $parsedId,
            $apiVersion
        }

        try {
            $colEnvironments = @(
                do {
                    $result = Invoke-BapSdkRequest `
                        -Resource @{ Builder = $builderName } `
                        -Method 'GetAsync' `
                        -Token $tokenValue `
                        -RequestUrl $requestUri

                    if ($isEnvironmentId) {
                        $result
                        $requestUri = $null
                    }
                    else {
                        $result.value
                        $requestUri = $result.'@odata.nextLink'
                    }
                } while (-not [string]::IsNullOrWhiteSpace($requestUri))
            )
        }
        catch {
            $errorText = "$($_.Exception.Message) $($_.Exception.InnerException.Message)"

            if ($errorText -match '403|Forbidden') {
                $messageString = "The Power Platform environment management API denied access (HTTP 403). Discovery needs the Power Platform Administrator tenant role. For now - use Get-BapEnvironment to discover environments instead."
                Write-PSFMessage -Level Warning `
                    -Message $messageString

                return
            }

            throw
        }

        $colRes = @(
            $colEnvironments |
            Where-Object {
                ($isEnvironmentId) `
                    -or ($_.id -like $EnvironmentId) `
                    -or ($_.displayName -like $EnvironmentId)
            } | Sort-Object -Property displayName |
            Select-PSFObject -TypeName 'D365Bap.Tools.PpacEnvironment' `
                -Property 'id as PpacEnvId',
            'id as EnvId',
            'displayName as PpacEnvName',
            'displayName as EnvName',
            'type as Sku',
            'finOpsMetadata.type as EnvType',
            @{ Name = 'Managed'; Expression = { $_.protectionLevel -eq 'Standard' } },
            *
        )

        if ($AsExcelOutput) {
            $colRes |
            Export-Excel -WorksheetName 'Get-PpacEnvironment' `
                -WarningAction SilentlyContinue

            return
        }

        $colRes
    }
}