internal/functions/batch/Send-EntraBatchEnvelope.ps1
|
function Send-EntraBatchEnvelope { <# .SYNOPSIS Posts one Graph $batch envelope and returns its sub-responses, read in C#. .DESCRIPTION The sequential transport of Invoke-EntraParallelBatch (-ThrottleLimit 1) and the seam the tests mock. Posts the envelope through the shared [PSMicrosoftEntraID.Batch.GraphBatchClient], which keeps the connection open and parses the raw answer in C#, so no PowerShell objects are built for the payload: each sub-response comes back as a [PSMicrosoftEntraID.Batch.BatchSubResponse] with status, Retry-After, paging links and the raw body - and with -ElementType the items of every successful page as typed objects. A failure of the envelope itself comes back as one synthetic sub-response per request: the HTTP status of the envelope when it was answered, 421 when it was refused before it was sent (not https, not the host of -AuthorizedUrl), 504 without an answer within PSMicrosoftEntraID.Settings.Request.TimeoutSeconds, 502 for an answer that is no $batch response, 503 for a network failure. Their messages never quote the answer. The envelope runs as a task waited for in short steps: Ctrl+C or a stopped pipeline cancels it at once instead of waiting for an answer that may never come. .PARAMETER Uri The $batch URL of the service. .PARAMETER Header The request headers, including Authorization. .PARAMETER Envelope The batch body: @{ requests = @( @{ id; method; url; headers; body } ) }. .PARAMETER AuthorizedUrl The service URL of the token in -Header. The client posts the envelope only over https to its scheme, host and port. .PARAMETER ElementType The type of one item of a page: successful pages are deserialized into it (Items) straight from their JSON. .EXAMPLE PS C:\> Send-EntraBatchEnvelope -Uri 'https://graph.microsoft.com/v1.0/$batch' -Header $header -Envelope $envelope -AuthorizedUrl 'https://graph.microsoft.com/v1.0' Posts the envelope and returns the sub-responses. #> [OutputType([PSMicrosoftEntraID.Batch.BatchSubResponse[]], [System.Array])] [CmdletBinding()] param ( [Parameter(Mandatory = $true)] [string] $Uri, [Parameter(Mandatory = $true)] [hashtable] $Header, [Parameter(Mandatory = $true)] [hashtable] $Envelope, [Parameter(Mandatory = $true)] [string] $AuthorizedUrl, [type] $ElementType ) [string[]] $ids = @($Envelope.requests | ForEach-Object { [string]$_.id }) [string] $body = $Envelope | ConvertTo-Json -Depth 20 -Compress [int] $timeoutSeconds = Get-PSFConfigValue -FullName 'PSMicrosoftEntraID.Settings.Request.TimeoutSeconds' -Fallback 600 $cancel = [System.Threading.CancellationTokenSource]::new() $task = [PSMicrosoftEntraID.Batch.GraphBatchClient]::SendAsync($Uri, $Header, $body, $ids, $timeoutSeconds, $AuthorizedUrl, $ElementType, $cancel.Token) try { # Short waits: PowerShell stops a pipeline only between statements, never inside a blocking .NET call. WaitAny # never throws; GetResult() raises a failure of the task as itself, not wrapped in an AggregateException. while ([System.Threading.Tasks.Task]::WaitAny([System.Threading.Tasks.Task[]]@($task), 200) -lt 0) { } , $task.GetAwaiter().GetResult() } finally { # Stopped while waiting: the envelope is cancelled, its connection closed. The source is released either way; # the envelope's own linked source keeps working after it is disposed. if (-not $task.IsCompleted) { $cancel.Cancel() } $cancel.Dispose() } } |