en-US/about_Mgx.help.txt
|
TOPIC about_Mgx SHORT DESCRIPTION Resilient companion for Microsoft.Graph PowerShell. Adds retry, circuit breaker, rate limiting, streaming pagination, batching, and fan-out to any Graph API endpoint. LONG DESCRIPTION Mgx is a PowerShell module that extends Microsoft.Graph with production- grade resilience and performance. It reuses your existing Connect-MgGraph authentication and works alongside the Microsoft.Graph SDK, not instead of it. Key capabilities: Streaming pagination Invoke-MgxRequest returns results to the pipeline as they arrive instead of buffering the entire collection in memory. This keeps memory constant regardless of result set size. Fan-out concurrency Pipeline input with {id} template substitution dispatches multiple requests in parallel. Useful for per-entity lookups that would otherwise require an N+1 loop. Automatic batching Invoke-MgxBatchRequest bundles up to 20 requests per $batch call, reducing HTTP round-trips for bulk create, update, and delete operations. Built-in resilience Every request passes through a Polly pipeline that handles HTTP 429 throttling (with Retry-After), transient 5xx errors, circuit breaking, and token-bucket rate limiting. No configuration is required; defaults are tuned for Graph API limits. Zero-change SDK resilience Enable-MgxResilience injects the same resilience pipeline into the Microsoft.Graph SDK HTTP transport. Existing scripts that use Get-MgUser, Get-MgGroup, and other SDK cmdlets gain retry, circuit breaker, and rate limiting without any code changes. Delta sync Sync-MgxDelta performs incremental delta queries with automatic state file management, returning only changes since the last sync. JSONL export Export-MgxCollection streams paginated results directly to a JSONL file on disk, bypassing object conversion. Checkpoint files allow interrupted exports to resume where they left off. Relation enrichment Expand-MgxRelation enriches Graph objects with related data via concurrent fan-out, handling both collection and singleton endpoints. Content downloads Get-MgxContent downloads file and media content whole or by byte range. Graph answers a content request with a redirect to a pre-authenticated download host; that second hop carries no bearer token, its host is validated against an allowlist before anything is sent, and the capability URL is kept out of debug output. CMDLETS Invoke-MgxRequest General-purpose resilient client for any Microsoft Graph endpoint. Invoke-MgxBatchRequest Bundle multiple Graph API requests into $batch calls. Export-MgxCollection Stream paginated Graph API results directly to a JSONL file. Expand-MgxRelation Enrich Graph objects with related data via concurrent fan-out. Sync-MgxDelta Incremental sync via Microsoft Graph delta queries. Get-MgxContent Download file and media content, whole or by byte range, over the two-hop pre-authenticated download path. Enable-MgxResilience Inject Polly resilience into the Microsoft.Graph SDK HTTP transport. Disable-MgxResilience Remove Polly resilience injection from the Microsoft.Graph SDK. Get-MgxResilience Check the current state of resilience injection. Set-MgxOption Configure resilience options for all Mgx cmdlets. Get-MgxOption Display current resilience and rate limiting configuration. Get-MgxTelemetry Return accumulated session telemetry from the resilience pipeline. RESILIENCE All Mgx cmdlets share a single Polly resilience pipeline composed of four layers, preceded by an adaptive pacing gate: Adaptive pacing gate (on by default) Spaces requests BEFORE they are sent, rather than reacting after a 429. It learns a rate per workload from throttling signals - additive increase while clean, multiplicative decrease on a throttle - and keeps Drive, Directory and other workloads in separate buckets, so one throttled workload does not slow the rest. A cold session starts conservatively and ramps up. It applies to every request, including the Enable-MgxResilience SDK-bridge path. Batch outer POSTs are the one exemption: batching runs its own item-level AIMD, and two controllers on one workload would compound their backoff. Disable with Set-MgxOption -NoAdaptivePacing. Inspect the learned state with Get-MgxTelemetry. Rate limiter (token bucket) Prevents outbound request bursts from triggering Graph API throttling. Default: 200 burst, 50 tokens replenished per second. Retry with exponential backoff Retries transient failures (HTTP 429, 500, 502, 503, 504) up to 7 times with exponentially increasing delays and jitter. Honors the Retry-After header when present. Circuit breaker Opens the circuit after 10% failure ratio over a 30-second sampling window (minimum 40 requests), rejecting requests for 15 seconds before retesting. Trips on 500/502/503/504; does not trip on 429. Timeout Per-attempt timeout (default 30s) and total timeout across all retries (default 300s) prevent requests from hanging indefinitely. The pipeline is shared across all cmdlet invocations within a session. Use Set-MgxOption to tune parameters at runtime. AUTHENTICATION Mgx has no connect cmdlet of its own. It follows the context established by Connect-MgGraph and builds its HTTP client from it. That client is cached for the session and rebuilt automatically whenever the effective identity changes - a different tenant, application, account, certificate, credential type, scope set, or cloud. Re-running Connect-MgGraph with another service principal therefore takes effect on the next Mgx call, with no need to restart PowerShell. Run any cmdlet with -Verbose to see the rebuild reported. If Enable-MgxResilience is active when the identity changes, Mgx re-injects resilience into the Microsoft.Graph SDK client as well. When it cannot, it warns and asks you to run Enable-MgxResilience again. CONFIGURATION Use Get-MgxOption to inspect the current resilience settings and Set-MgxOption to change them. Only explicitly passed parameters are modified; all others retain their current values. Get-MgxOption Set-MgxOption -MaxRetryAttempts 5 -RateLimitBurst 100 Set-MgxOption -Reset Configurable parameters include rate limit burst and replenish rate, maximum retry count, circuit breaker failure ratio and sampling duration, per-request and total timeout values, and batch item pacing rate (BatchItemsPerSecond, default 20 items/sec). TRACING REQUESTS Run any cmdlet with -Debug to see the HTTP traffic it produces: method and absolute URL, request headers and body, response status, elapsed time, and the Graph diagnostic headers (request-id, x-ms-ags-diagnostic, Retry-After, throttle and rate limit headers). Retries are traced individually, so a throttled call shows every attempt. Invoke-MgxRequest /directoryObjects/getByIds -Method POST -Body @{ ids = @('<id>') } -Debug The trace covers pagination, fan-out and $batch as well. Authorization and credential-looking JSON fields (password, secret, credential, token, key) are redacted, and bodies are truncated at 4 KB. Tracing buffers each response body in memory, so leave -Debug off for large exports. Use -Verbose instead for the higher-level story: retries, throttle proximity, pacing changes and client rebuilds. EXAMPLES Example 1: List all users with streaming pagination Connect-MgGraph -Scopes "User.Read.All" Import-Module Mgx Invoke-MgxRequest /users -All -Property displayName,mail Example 2: Add resilience to existing Microsoft.Graph scripts Connect-MgGraph -Scopes "User.Read.All" Import-Module Mgx Enable-MgxResilience Get-MgUser -All # now retries on 429/5xx automatically Example 3: Fan-out to get managers for multiple users $userIds | Invoke-MgxRequest '/users/{id}/manager' REQUIREMENTS PowerShell 7.4 or later (Core edition; targets .NET 8, runs on newer). Microsoft.Graph.Authentication 2.10.0 or later supplies the token, but it is not a declared dependency: mgx resolves auth reflectively at call time, so the module imports without it and does not install a second copy beside one you already load. Cmdlets that need a token report GraphAuthModuleNotLoaded when it is absent. SEE ALSO about_Mgx_Tuning Invoke-MgxRequest Invoke-MgxBatchRequest Export-MgxCollection Expand-MgxRelation Sync-MgxDelta Get-MgxContent Enable-MgxResilience Disable-MgxResilience Get-MgxResilience Set-MgxOption Get-MgxOption Get-MgxTelemetry |