functions/batch/Invoke-PSEntraIDBatchRequest.ps1
|
function Invoke-PSEntraIDBatchRequest { <# .SYNOPSIS Invokes Microsoft Graph batch requests from BatchRequestPayload objects and returns the requests together with their responses. .DESCRIPTION This function expects pipeline input of BatchRequestPayload objects (such as those produced by New-PSEntraIDBatchRequest). Each BatchRequestPayload contains up to 20 sub-requests. The sub-requests are sent through the module's batch engine: they are packed into Graph $batch envelopes of 20, and Settings.Batch.ThrottleLimit envelopes (default 4) are in flight at the same time. The payloads are taken from the pipeline in blocks: once the buffered sub-requests fill Settings.Batch.StreamBlockSize envelopes (default 20), the block is sent and its results are written before more input is taken; the rest is sent when the pipeline ends. Results therefore flow while input is still arriving. Each sub-request is retried on its own: one answered 408, 429 or 5xx (except 501 and 505) is sent again after its own Retry-After (at most 5 minutes; otherwise 2^attempt seconds with jitter), up to Settings.Batch.RetryCount times (default 5). A POST sub-request is sent again only on 429 and 503, where Graph says it did not carry it out. A 400 whose Graph error code is Directory_ConcurrencyViolation (a change that collided with another one) is sent again for every method; every other 400 is final. The envelope itself is never sent again as a whole, and nothing else retries. For each payload one BatchResponsePayload is returned, in the order of the input (across blocks too): Requests = the sub-requests of the payload Responses = one response per sub-request, in the order of the requests (Id, Status, Headers, Body) A sub-request that failed for good keeps its response (with its status) in the output and is also reported as ONE non-terminating error whose target is the request; the run ends with ONE warning summarising failures and re-sends of all blocks. With -EnableException no error records are written and the command throws at the end, after all results were returned. Ctrl+C or a pipeline stopped downstream (Select-Object -First) cancels every envelope still in flight, and no further block is sent. .PARAMETER InputObject An array of BatchRequestPayload objects to be processed. Each object has a .Requests list containing up to 20 Request objects. .PARAMETER EnableException This parameter disables user-friendly warnings and enables the throwing of exceptions. Less user friendly, but allows catching exceptions in calling scripts. .PARAMETER Force Sends the batches without asking for confirmation. .PARAMETER WhatIf Enables the function to simulate what it will do instead of actually executing. .PARAMETER Confirm Prompts for confirmation before the command makes a change. -Confirm:$false suppresses that prompt. Bound explicitly it wins over -Force, whatever its value - so -Confirm:$true prompts even alongside -Force, and the two are alternatives rather than a pair. Left unbound, the decision belongs to this command's ConfirmImpact and the session ConfirmPreference, which is the PowerShell default behaviour. .EXAMPLE PS C:\> $payloads | Invoke-PSEntraIDBatchRequest -EnableException Sends one or more BatchRequestPayload objects (created by New-PSEntraIDBatchRequest) to the Microsoft Graph $batch endpoint and returns BatchResponsePayload objects that correlate the original requests with the responses returned by Graph. #> [OutputType([PSMicrosoftEntraID.Batch.BatchResponsePayload])] [CmdletBinding( SupportsShouldProcess = $true, # enables -WhatIf and -Confirm ConfirmImpact = 'High' )] param( [Parameter( Mandatory = $true, ValueFromPipeline = $true, HelpMessage = "One or more BatchRequestPayload objects, each with up to 20 sub-requests." )] [PSMicrosoftEntraID.Batch.BatchRequestPayload[]] $InputObject, [Parameter()] [switch] $EnableException, [Parameter()] [switch] $Force ) begin { [string] $service = Get-PSFConfigValue -FullName ('{0}.Settings.DefaultService' -f $script:ModuleName) Assert-EntraConnection -Service $service -Cmdlet $PSCmdlet # -Force skips the prompt; an explicitly bound -Confirm, $true or $false, wins over it. if ($Force -and -not $PSBoundParameters.ContainsKey('Confirm')) { $ConfirmPreference = 'None' } [string] $platform = Get-PSFLocalizedString -Module $script:ModuleName -Name 'Identity.Platform' [string] $actionText = Get-PSFLocalizedString -Module $script:ModuleName -Name 'Batch.Invoke' # The summary is written from the block scriptblock too, where $MyInvocation is the scriptblock's. [string] $commandName = $MyInvocation.MyCommand.Name # A block is sent once its sub-requests fill this many envelopes of 20. [int] $blockRequests = 20 * (Get-PSFConfigValue -FullName ('{0}.Settings.Batch.StreamBlockSize' -f $script:ModuleName) -Fallback 20) # The confirmed payloads of the current block, the engine's requests for them, and their state by the payload's # position in the whole run (labels and keys count across blocks). $requests = [System.Collections.Generic.List[object]]::new() $pending = @{} $emit = @{ Next = 0; Count = 0; Sent = 0 } # The run's report: failures and re-sends of every block, for the one summary. [hashtable] $report = @{} # Results are written in the order of the input: a payload once all its responses arrived and every payload # before it was written. $writeReady = { while ($pending.ContainsKey($emit.Next) -and $pending[$emit.Next].Responses.Count -ge $pending[$emit.Next].Expected) { $state = $pending[$emit.Next] $pending.Remove($emit.Next) $emit.Next++ [PSMicrosoftEntraID.Batch.BatchResponsePayload]@{ Requests = $state.Payload.Requests Responses = [PSMicrosoftEntraID.Batch.Response[]]@(foreach ($request in @($state.Payload.Requests)) { $state.Responses[[string]$request.Id] }) } } } # Sends the buffered block through the engine and writes its results; the next block starts empty. $sendBlock = { # Payloads without requests at the head of the block. & $writeReady if ($requests.Count -eq 0) { return } [object[]] $blockArray = $requests.ToArray() $requests.Clear() $emit.Sent += $blockArray.Count [bool] $completed = $false try { Invoke-EntraParallelBatch -Request $blockArray -Service $service -Report $report | & { process { $page = $_ [string[]] $keyParts = ([string]$page.Key).Split('/', 2) [int] $index = [int]$keyParts[0] - 1 $state = $pending[$index] $request = @($state.Payload.Requests) | Where-Object { [string]$_.Id -eq $keyParts[1] } | Select-Object -First 1 $body = $null if ($page.Body) { $body = $page.Body | ConvertFrom-Json } elseif ($page.Error) { # No answer from Graph (refused, cancelled, timed out, unreadable): the reason in Graph's shape. $body = [pscustomobject]@{ error = [pscustomobject]@{ code = 'PSMicrosoftEntraID.BatchClient'; message = $page.Error } } } $headers = $null if ($page.Headers) { $headers = $page.Headers | ConvertFrom-Json } $state.Responses[$keyParts[1]] = [PSMicrosoftEntraID.Batch.Response]@{ Id = $keyParts[1] Status = $page.Status Headers = $headers Body = $body } if (-not $page.Succeeded) { [string] $label = (Get-PSFLocalizedString -Module $script:ModuleName -Name 'Batch.Request.Label') -f ($index + 1), $keyParts[1] Write-EntraItemFailure -Cmdlet $PSCmdlet -Report $report -Target $request -Label $label -Status $page.Status -Reason $page.Error -EnableException $EnableException.IsPresent } & $writeReady } } $completed = $true } finally { # Ended early by an error with -EnableException: the summary of what was sent until then. A stopped # pipeline (Ctrl+C, Select-Object -First) writes nothing more; the engine cancelled what was in flight. if (-not $completed -and $EnableException) { Write-EntraBatchSummary -Report $report -FunctionName $commandName } } # Not expected - the engine returns one final page per request - but a payload missing a response is still # written, with the responses it has. foreach ($index in @($pending.Keys)) { $pending[$index].Expected = $pending[$index].Responses.Count } & $writeReady } } process { foreach ($payload in $InputObject) { # One confirmation per payload: No skips it, Yes to All and No to All answer the payloads that follow. if (-not $PSCmdlet.ShouldProcess($platform, ($actionText -f ($payload.Requests.Id -join ',')))) { continue } # The engine's requests. A key names the payload (its position in the run) and the request id. [int] $index = $emit.Count $emit.Count++ [object[]] $payloadRequests = @($payload.Requests) $pending[$index] = @{ Payload = $payload; Responses = @{}; Expected = $payloadRequests.Count } foreach ($request in $payloadRequests) { $entry = [ordered]@{ Key = ('{0}/{1}' -f ($index + 1), $request.Id); Method = $request.Method; Url = $request.Url } # Headers and body only when they carry something: Graph rejects a GET sub-request with a body, and the # Request class defaults both to an empty hashtable. if ($request.Headers -and $request.Headers.Count -gt 0) { $entry.Headers = $request.Headers } if ($request.Body -and $request.Body.Count -gt 0) { $entry.Body = $request.Body } $requests.Add([pscustomobject]$entry) } # A full block goes out now: its results are written before more input is taken. if ($requests.Count -ge $blockRequests) { & $sendBlock } } } end { & $sendBlock Write-EntraBatchSummary -Report $report -FunctionName $commandName if ($EnableException -and $report['Items.Reported'] -and $report['Items.Reported'].Count -gt 0) { [string] $message = (Get-PSFLocalizedString -Module $script:ModuleName -Name 'Batch.Failed') -f $report['Items.Reported'].Count, $emit.Sent Invoke-TerminatingException -Cmdlet $PSCmdlet -Message $message -Category ConnectionError } } } |