functions/Get-FscmOdata.ps1
|
<# .SYNOPSIS Queries a Finance and Operations OData entity. .DESCRIPTION Sends a GET request to the Finance and Operations OData endpoint and returns the matching records. Handles authentication, query filters, cross-company access, nextLink pagination, and automatic retries for throttled requests. .PARAMETER EnvironmentId Environment name, environment GUID (PPAC), or LCS environment ID. .PARAMETER Entity The OData entity collection name to query, e.g. "SysAADClients". .PARAMETER ODataQuery Optional query string without the leading "?", e.g. '$filter=IsActive eq true'. .PARAMETER CrossCompany Adds "cross-company=true" so records from all legal entities are returned. .PARAMETER TraverseNextLink Follows "@odata.nextLink" pagination and accumulates every page in the result. .PARAMETER ThrottleSeed Random delay in seconds, between 1 and this value, after each page request. .PARAMETER AsExcelOutput Exports the retrieved records to an Excel file instead of the pipeline. .EXAMPLE PS C:\> Get-FscmOdata -EnvironmentId "ContosoEnv" -Entity "SysAADClients" Retrieves every record from one OData entity. It uses -EnvironmentId to select the "ContosoEnv" environment. It uses -Entity to select the "SysAADClients" entity set. .EXAMPLE PS C:\> Get-FscmOdata -EnvironmentId "ContosoEnv" -Entity "SystemUsers" -ODataQuery "`$filter=IsActive eq true" Retrieves only active system users through a query filter. It uses -EnvironmentId to select the "ContosoEnv" environment. It uses -Entity to select the "SystemUsers" entity set. It uses -ODataQuery to send the filter expression. .EXAMPLE PS C:\> Get-FscmOdata -EnvironmentId "ContosoEnv" -Entity "SystemUsers" -CrossCompany Retrieves system users across all legal entities. It uses -EnvironmentId to select the "ContosoEnv" environment. It uses -Entity to select the "SystemUsers" entity set. It uses -CrossCompany to include every legal entity. .EXAMPLE PS C:\> Get-FscmOdata -EnvironmentId "ContosoEnv" -Entity "SysAADClients" -TraverseNextLink Follows pagination links until every page is returned. It uses -EnvironmentId to select the "ContosoEnv" environment. It uses -Entity to select the "SysAADClients" entity set. It uses -TraverseNextLink to request all pages. .EXAMPLE PS C:\> Get-FscmOdata -EnvironmentId "ContosoEnv" -Entity "SysAADClients" -TraverseNextLink -ThrottleSeed 3 Pauses between pages to reduce the risk of throttling. It uses -EnvironmentId to select the "ContosoEnv" environment. It uses -Entity to select the "SysAADClients" entity set. It uses -TraverseNextLink to request all pages. It uses -ThrottleSeed 3 to wait up to three seconds between pages. .EXAMPLE PS C:\> Get-FscmOdata -EnvironmentId "ContosoEnv" -Entity "SysAADClients" -AsExcelOutput Exports every retrieved record to an Excel file. It uses -EnvironmentId to select the "ContosoEnv" environment. It uses -Entity to select the "SysAADClients" entity set. It uses -AsExcelOutput to write the records to a workbook. .NOTES Author: Mötz Jensen (@Splaxi) #> function Get-FscmOdata { [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseSingularNouns", "", Justification = "OData is the name of the protocol.")] [CmdletBinding(DefaultParameterSetName = 'Default')] [OutputType([PSCustomObject[]])] param ( [Parameter (Mandatory = $true)] [ValidateNotNullOrEmpty()] [string] $EnvironmentId, [Parameter(Mandatory = $true, ParameterSetName = "Default")] [Parameter(Mandatory = $true, ParameterSetName = "NextLink")] [ValidateNotNullOrEmpty()] [string] $Entity, [string] $ODataQuery, [switch] $CrossCompany, [Parameter(Mandatory = $true, ParameterSetName = "NextLink")] [switch] $TraverseNextLink, [Parameter(ParameterSetName = "NextLink")] [int] $ThrottleSeed, [switch] $AsExcelOutput ) begin { $envObj = Get-Environment -EnvironmentId $EnvironmentId | Select-Object -First 1 $baseUri = $envObj.FnOEnvUri -replace '.com/', '.com' $objSecureToken = Get-BapAccessToken -ResourceUrl $baseUri $tokenFnoOdataValue = ConvertFrom-SecureString -AsPlainText ` -SecureString $objSecureToken $hashHeadersFnO = @{ "Authorization" = "Bearer $($tokenFnoOdataValue)" } } process { if (Test-PSFFunctionInterrupt) { return } [System.UriBuilder] $odataEndpoint = $baseUri $odataEndpoint.Path = "/data/$Entity" if (-not ([string]::IsNullOrEmpty($ODataQuery))) { $odataEndpoint.Query = "$ODataQuery" } if ($CrossCompany) { $odataEndpoint.Query = $($odataEndpoint.Query + "&cross-company=true").Replace("?", "") } [System.Collections.Generic.List[System.Object]] $resArray = @() $localUri = $odataEndpoint.Uri.AbsoluteUri $429Attempts = 0 $maxRetries = 3 do { $429Retry = $false try { $resGet = Invoke-RestMethod -Method Get ` -Uri $localUri ` -Headers $hashHeadersFnO $429Attempts = 0 $resArray.AddRange($resGet.Value) if ($($resGet.'@odata.nextLink') -match ".*(/data/.*)") { $localUri = "$baseUri$($Matches[1])" } if ($ThrottleSeed) { $tmpThrottleDelay = Get-Random -Minimum 1 ` -Maximum $ThrottleSeed Start-Sleep -Seconds $tmpThrottleDelay } } catch [System.Net.WebException] { if ($_.exception.response.statuscode -eq 429) { $429Retry = $true $429Attempts++ $retryWaitSec = $_.exception.response.Headers["Retry-After"] if (-not ($retryWaitSec -gt 0)) { $retryWaitSec = 10 } Write-PSFMessage -Level Host ` -Message "Hit a 429 status code. Will wait for: <c='em'>$retryWaitSec</c> seconds before trying again. Attempt (<c='em'>$429Attempts</c> of <c='em'>$maxRetries</c>)" if ($429Attempts -ge $maxRetries) { Write-PSFMessage -Level Warning ` -Message "Reached maximum of <c='em'>$maxRetries</c> retry attempts due to throttling. Returning <c='em'>$($resArray.Count)</c> collected records." break } Start-Sleep -Seconds $retryWaitSec } else { Throw } } } while ($429Retry -or ($TraverseNextLink -and $resGet.'@odata.nextLink')) if ($resArray.Count -gt 0) { $res = $resArray.ToArray() } if ($AsExcelOutput) { $res | Export-Excel -WorksheetName "Get-FscmOdata" return } $res } end { } } |