Private/Invoke-MgGraphRequestCustom.ps1
|
<#
.Synopsis Created on: 03/04/2024 Updated on: 16/11/2026 Created by: Ben Whitmore Filename: Invoke-MgGraphRequestCustom.ps1 .Description Function to invoke a request to the Microsoft Graph API using the Microsoft.Graph.Authentication module from the Microsoft Graph SDK. Transient failures (HTTP 429, 500, 502, 503, 504 and network errors) are retried, honouring the Retry-After header when present. Throws if there is no valid Microsoft Graph connection. .PARAMETER LogId The component (script name) passed as LogID to the 'Write-Log' function. This parameter is built from the line number of the call from the function up the .PARAMETER GraphUrl Graph Url to use .PARAMETER Method The HTTP method to use for the request .PARAMETER Endpoint The endpoint to use for the request .PARAMETER Resource The resource to use for the request .PARAMETER Body The body of the request .PARAMETER OutputBody If True, output body of the request to console and log. Bodies containing fileEncryptionInfo are never logged .PARAMETER ContentType The content type for the PATCH or POST request .PARAMETER MaxRetries The maximum number of retries for transient failures. Default is 5 #> function Invoke-MgGraphRequestCustom { param ( [Parameter(Mandatory = $false, ValuefromPipeline = $false, HelpMessage = "The component (script name) passed as LogID to the 'Write-Log' function")] [string]$LogId = $($MyInvocation.MyCommand).Name, [Parameter(Mandatory = $false, ValueFromPipeline = $false, HelpMessage = 'Graph Url to use')] [string]$GraphUrl = 'https://graph.microsoft.com', [Parameter(Mandatory = $true, ValueFromPipeline = $false, HelpMessage = 'The HTTP method to use for the request')] [ValidateSet("GET", "POST", "PATCH", "DELETE")] [string]$Method, [Parameter(Mandatory = $false, ValueFromPipeline = $false, HelpMessage = 'The endpoint to use for the request')] [string]$Endpoint = 'beta', [Parameter(Mandatory = $true, ValueFromPipeline = $false, HelpMessage = 'The resource to use for the request')] [string]$Resource, [Parameter(Mandatory = $false, ValueFromPipeline = $false, HelpMessage = 'The body of the request')] [string]$Body, [Parameter(Mandatory = $false, ValueFromPipeline = $false, HelpMessage = 'If True, output body of the request to console and log. Useful for debugging')] [bool]$OutputBody = $false, [Parameter(Mandatory = $false, ValueFromPipeline = $false, HelpMessage = 'The content type for the PATCH or POST request')] [string]$ContentType = "application/json", [Parameter(Mandatory = $false, ValueFromPipeline = $false, HelpMessage = 'The maximum number of retries for transient failures')] [int]$MaxRetries = 5 ) try { # First check if we already have a valid connection with required scopes if (-not (Test-MgConnection)) { throw "No valid Microsoft Graph connection found. Please call Connect-MgGraphCustom first or pass at least the TenantId and ClientId parameters to New-Win32app" } # Build the Uri $graphUri = "$($GraphUrl)/$($Endpoint)/$($Resource)" if ($Body -and $OutputBody) { $bodyToLog = $Body if ($Body -match 'fileEncryptionInfo') { $bodyToLog = '<redacted: contains fileEncryptionInfo>' } Write-LogAndHost -Message ("Building Uri for Graph request. Method: '{0}', Uri: '{1}', Body: '{2}'" -f $Method, $graphUri, $bodyToLog) -LogId $LogId -ForegroundColor Cyan } else { Write-LogAndHost -Message ("Building Uri for Graph request. Method: '{0}', Uri: '{1}'" -f $Method, $graphUri) -LogId $LogId -ForegroundColor Cyan } $attempt = 0 while ($true) { try { # Call Graph API and get JSON response switch ($Method) { "GET" { $graphResult = Invoke-MgGraphRequest -Uri $graphUri -Method $Method -ErrorAction Stop } "POST" { $graphResult = Invoke-MgGraphRequest -Uri $graphUri -Method $Method -Body $Body -ContentType $ContentType -ErrorAction Stop } "PATCH" { $graphResult = Invoke-MgGraphRequest -Uri $graphUri -Method $Method -Body $Body -ContentType $ContentType -ErrorAction Stop } "DELETE" { $graphResult = Invoke-MgGraphRequest -Uri $graphUri -Method $Method -ErrorAction Stop } } return $graphResult } catch { $statusCode = Get-GraphErrorStatusCode -ErrorRecord $_ $retryable = $false if ($Method -in @('POST', 'PATCH')) { # Not idempotent: a request that reached Graph but lost its response would run twice # (for example two Win32 apps). Only throttled requests (429) are known not to have run $retryable = ($statusCode -eq 429) } elseif ($null -ne $statusCode) { $retryable = @(429, 500, 502, 503, 504) -contains $statusCode } else { $retryable = Test-GraphTransientNetworkError -ErrorRecord $_ } if (-not $retryable -or $attempt -ge $MaxRetries) { throw } $attempt++ $retryAfter = Get-GraphRetryAfterSeconds -ErrorRecord $_ if ($null -ne $retryAfter -and $retryAfter -gt 0) { $delay = [int][Math]::Ceiling($retryAfter) } else { $delay = [int][Math]::Min(60, [Math]::Pow(2, $attempt)) } Write-LogAndHost -Message ("Graph request '{0}' failed (status '{1}'): {2}. Retry {3}/{4} in {5} seconds" -f $Method, $statusCode, $_.Exception.Message, $attempt, $MaxRetries, $delay) -LogId $LogId -Severity 2 Start-Sleep -Seconds $delay } } } catch { Write-LogAndHost -Message ([string]$_.Exception.Message) -LogId $LogId -Severity 3 throw } } function Get-GraphErrorStatusCode { param($ErrorRecord) try { $response = $ErrorRecord.Exception.Response if ($null -ne $response -and $null -ne $response.StatusCode) { return [int]$response.StatusCode } } catch { Write-Verbose "Unable to read status code from error: $($_.Exception.Message)" } return $null } function Get-GraphRetryAfterSeconds { param($ErrorRecord) try { $response = $ErrorRecord.Exception.Response if ($null -eq $response -or $null -eq $response.Headers) { return $null } # System.Net.Http.HttpResponseMessage $retryAfter = $response.Headers.RetryAfter if ($null -ne $retryAfter) { if ($null -ne $retryAfter.Delta) { return [double]$retryAfter.Delta.TotalSeconds } if ($null -ne $retryAfter.Date) { $seconds = ($retryAfter.Date - [System.DateTimeOffset]::UtcNow).TotalSeconds if ($seconds -gt 0) { return [double]$seconds } } } } catch { Write-Verbose "Unable to read Retry-After from error: $($_.Exception.Message)" } return $null } function Test-GraphTransientNetworkError { param($ErrorRecord) $exception = $ErrorRecord.Exception while ($null -ne $exception) { $typeName = $exception.GetType().FullName if ($typeName -match 'HttpRequestException|WebException|SocketException|IOException|TaskCanceledException|TimeoutException') { return $true } $exception = $exception.InnerException } return $false } |