functions/Get-PpacTenantEntitlement.ps1
|
<# .SYNOPSIS Get tenant licensing entitlements. .DESCRIPTION Retrieves Power Platform licensing entitlements, including consumed capacity, pay-as-you-go usage, and backing licenses. .PARAMETER EntitlementId Entitlement id filter. Wildcards are accepted; expansion misses skip quietly. Default: * .PARAMETER AsExcelOutput Instructs the cmdlet to output the results as an Excel file. .EXAMPLE PS C:\> Get-PpacTenantEntitlement Lists every tenant licensing entitlement. .EXAMPLE PS C:\> Get-PpacTenantEntitlement -EntitlementId "AI" Returns the AI licensing entitlement. It uses -EntitlementId to select the entitlement. .EXAMPLE PS C:\> Get-PpacTenantEntitlement -EntitlementId "Power*" Lists entitlements matching the filter. It uses -EntitlementId to filter on the entitlement id. .EXAMPLE PS C:\> Get-PpacTenantEntitlement -AsExcelOutput Exports tenant licensing entitlements to an Excel workbook. It uses -AsExcelOutput to write an Excel file. .NOTES Author: d365bap.tools contributors #> function Get-PpacTenantEntitlement { [CmdletBinding()] [OutputType('D365Bap.Tools.PpacTenantEntitlement[]', [object[]])] param ( [Parameter(ValueFromPipelineByPropertyName = $true)] [SupportsWildcards()] [ValidateNotNullOrEmpty()] [string[]] $EntitlementId = '*', [switch] $AsExcelOutput ) begin { $objSecureToken = Get-BapAccessToken -PowerPlatform $tokenValue = ConvertFrom-SecureString -AsPlainText ` -SecureString $objSecureToken $apiVersion = $script:BapApiVersions.PowerPlatform $hashHeaders = @{ Authorization = "Bearer $tokenValue" } } process { if (Test-PSFFunctionInterrupt) { return } $colPatterns = @($EntitlementId) $colWildcardPatterns = @( $colPatterns | Where-Object { [Management.Automation.WildcardPattern]::ContainsWildcardCharacters($_) } ) $colKnownIds = @() if ($colWildcardPatterns.Count -gt 0) { $reportRequestUri = 'https://api.powerplatform.com/licensing/tenantCapacity/currencyReports?api-version={0}' ` -f $apiVersion try { $objReport = Invoke-RestMethod ` -Method Get ` -Uri $reportRequestUri ` -Headers $hashHeaders 4> $null } catch { $messageString = "Failed retrieving tenant currency reports. $($_.Exception.Message)" Write-PSFMessage -Level Important ` -Message $messageString ` -Exception $_.Exception Stop-PSFFunction -Message 'Stopping because the currency report request failed.' ` -Exception $_.Exception return } if ($objReport -is [array]) { $colReportEntries = @($objReport) } else { $colReportEntries = @($objReport.value) } $colKnownIds = @( $colReportEntries | ForEach-Object { $_.currencyType } | Where-Object { $_ } | Sort-Object -Unique ) } $colTargetIds = @( foreach ($itemPattern in $colPatterns) { if ([Management.Automation.WildcardPattern]::ContainsWildcardCharacters($itemPattern)) { $tmpMatchedIds = @( $colKnownIds | Where-Object { $_ -like $itemPattern } ) if ($tmpMatchedIds.Count -eq 0) { $messageString = "No licensing entitlement matches pattern '<c='em'>$itemPattern</c>'. Skipping." Write-PSFMessage -Level Warning ` -Message $messageString } foreach ($itemMatchedId in $tmpMatchedIds) { $itemMatchedId } } else { $itemPattern } } ) $colTargetIds = @( $colTargetIds | Sort-Object -Unique ) $colExplicitIds = @( $colPatterns | Where-Object { -Not [Management.Automation.WildcardPattern]::ContainsWildcardCharacters($_) } ) $colPayloads = @( foreach ($itemTargetId in $colTargetIds) { $requestUri = 'https://api.powerplatform.com/licensing/entitlements/{0}?api-version={1}' ` -f [uri]::EscapeDataString($itemTargetId), $apiVersion try { $tmpPayload = Invoke-RestMethod ` -Method Get ` -Uri $requestUri ` -Headers $hashHeaders 4> $null } catch { $statusCode = 0 try { $statusCode = $_.Exception.Response.StatusCode.value__ } catch { $statusCode = 0 } if ($statusCode -eq 404) { if ($itemTargetId -in $colExplicitIds) { $messageString = "No licensing entitlement found for '<c='em'>$itemTargetId</c>'. Skipping." Write-PSFMessage -Level Warning ` -Message $messageString continue } $messageString = "No licensing entitlement found for '<c='em'>$itemTargetId</c>'. Skipping." Write-PSFMessage -Level Verbose ` -Message $messageString continue } $messageString = "Failed retrieving licensing entitlement for '<c='em'>$itemTargetId</c>'." Write-PSFMessage -Level Warning ` -Message $messageString ` -ErrorRecord $_ Stop-PSFFunction -Message 'Stopping because the entitlement request failed.' ` -ErrorRecord $_ return } if ($null -eq $tmpPayload) { continue } $tmpPayload } ) $colRes = @( foreach ($itemPayload in $colPayloads) { $tmpLicenses = @( $itemPayload.entitlement.capacity.licenses | Where-Object { $_ } ) $tmpLicenseCount = $tmpLicenses.Count $tmpCategoryList = @( $itemPayload.productCategories | Where-Object { $_ } ) $tmpProductCategories = $tmpCategoryList -join ', ' $tmpEntitled = $itemPayload.entitlement.capacity.entitled.value $tmpConsumed = $itemPayload.entitlement.capacity.consumed.value $tmpLeft = $null if (-Not ($null -eq $tmpEntitled)) { if ($null -eq $tmpConsumed) { $tmpLeft = $tmpEntitled } else { $tmpLeft = $tmpEntitled - $tmpConsumed } } $itemPayload | Select-PSFObject -TypeName 'D365Bap.Tools.PpacTenantEntitlement' ` -Property ` 'entitlementId as EntitlementId', 'entitlement.unit as EntitlementUnit', 'entitlement.capacity.unit as CapacityUnit', 'entitlement.capacity.entitled.value as Entitled', 'entitlement.capacity.consumed.value as Consumed', 'entitlement.capacity.consumed.consumptionType as ConsumptionType', 'entitlement.capacity.consumed.lastUpdatedOn as LastUpdatedOn', 'entitlement.capacity.consumed.writeOff as WriteOff', 'entitlement.capacity.allocated.value as Allocated', 'entitlement.capacity.allocated.autoAllocated as AutoAllocated', 'entitlement.capacity.availableQuantity as Available', @{ Name = 'Left'; Expression = { $tmpLeft } }, 'entitlement.capacity.status as Status', @{ Name = 'Licenses'; Expression = { $tmpLicenseCount } }, @{ Name = 'ProductCategories'; Expression = { $tmpProductCategories } }, 'entitlement.payGo.entitled.value as PayGoEntitled', 'entitlement.payGo.consumed.value as PayGoConsumed', 'entitlement.payGo.consumed.consumptionType as PayGoConsumptionType', @{ Name = 'Raw'; Expression = { $itemPayload } } } ) if ($AsExcelOutput) { $colRes | Export-Excel -WorksheetName 'Get-PpacTenantEntitlement' ` -WarningAction SilentlyContinue return } $colRes } end { } } |