internal/Invoke-BBRESTMethod.ps1
|
<#
.Synopsis Calls the Blackboard REST API using the information provided. .DESCRIPTION First it sets a session if one doesn't exist. Then, based upon provided paramters, it calls the Blackboard REST API and pages through all results. It then returns all results. If the bearer token is expired, it will refresh it and re-execute the call... in theory it should be graceful. .EXAMPLE Invoke-BBRestMethod -API "/learn/api/public/v1/terms" ` -Method Get ` -ContentType application/json #> function Invoke-BBRESTMethod { [CmdletBinding(SupportsShouldProcess)] [Alias()] Param ( [Parameter(Mandatory=$true)] [string]$API, [ValidateSet("Get", "Post", "Delete", "Put", "Patch")] [string]$Method = 'Get', [string]$ContentType = 'application/json', [string]$Filter, [array]$Body = $null ) Begin { If(!($Filter -eq "")) { $extendedURL = $BBRESTVariables.ClientUrl + $API + '?' + $Filter }else { $extendedURL = $BBRESTVariables.ClientUrl + $API } if(!($Body -eq $null)){ $Body = $Body | ConvertTo-Json } $PagingExpected = $false $PagingRecieved = $false $AttemptCount = 0 } Process { $QueryResults = @() # Invoke REST method and fetch data until there are no pages left. #Establish session if one deoesn't exist if(!$BBRESTVariables.BearerToken){ write-verbose "Looks like the session doesn't exist yet. I'll create one" Set-BBRESTSession }else{ write-verbose $BBRESTVariables.BearerToken } if ($PSCmdlet.ShouldProcess($API,$Method,$ContentType)) { #This do will go until there are no more paged results. Because blackboard lets you know if there is a page expected do { write-verbose "Calling to: $extendedURL" $RetryWithNewSession = $false #Because the session can go bad at any time, we need to watch for that and try a call again if the session went out. #Attempt to call the api. If the bearer token is stale, meaning it returns a 402, it will refresh that token and attempt the call again. Try{ write-verbose "Invoke-BBRESTMethod is processing the following record: Invoke RestMethod: $Method ContentType: $ContentType Uri: $extendedURL Token: $($BBRESTVariables.BearerToken) Body: $Body" #If, from a previous call, paging is expected: if($PagingExpected){ while (($PagingExpected -eq $true) -and ($PagingRecieved -eq $false)) { #We've attempted to set a session $Results = Invoke-RestMethod -Method $Method ` -ContentType $ContentType ` -Uri $extendedURL ` -Authentication Bearer ` -Token $(ConvertTo-SecureString $($BBRESTVariables.BearerToken) -AsPlainText -Force) ` -Body $Body if($Results.results.Count -gt 0){ $PagingRecieved = $true }else { $PagingRecieved = $false } $AttemptCount ++ } }else { #First Call w/o paging if($RetryWithNewSession -eq $false -and $AttemptCount -gt 0){ Set-BBRESTSession $AttemptCount ++ $RetryWithNewSession = $true } $Results = Invoke-RestMethod -Method $Method ` -ContentType $ContentType ` -Uri $extendedURL ` -Authentication Bearer ` -Token $(ConvertTo-SecureString $($BBRESTVariables.BearerToken) -AsPlainText -Force) ` -Body $Body } #Check to see if the bearer token is invalid, or if another error happend. If the bearer token is invalid, get another one. At this point, i'm not quite sure how to handle other errors as I haven't seen them. } catch{ if($RetryWithNewSession -eq $false){ Set-BBRESTSession $RetryWithNewSession = $true }else{ Write-Verbose "An error happened. Already attempted to set the BBREST Session and still errored out" Throw $_.Exception } } #Set the returned results to be sent back once all calls are done. if ($null -eq $Results.results) { $QueryResults += $Results } else { $QueryResults += $Results.results } #Set the Paging variable to track if paging is expected for the next call. if ($($Results.paging.nextPage)) { $PagingExpected = $true $PagingRecieved = $false #Set the next API URL to be called. $extendedURL = $BBRESTVariables.ClientUrl + $($Results.paging.nextPage) } } until (!($($Results.paging.nextPage) -and ($RetryWithNewSession -eq $false))) } else { Write-Host "Invoke-BBRESTMethod would process the following record: Invoke RestMethod: $Method ContentType: $ContentType Uri: $extendedURL Token: $($BBRESTVariables.BearerToken) Body: $Body" -ForegroundColor Green #Do the rest call until there are no paged results left } } End { return $QueryResults } } |