Public/Get-GraphMapping.ps1
|
function Get-GraphMapping { <# .SYNOPSIS Maps and relates Microsoft Graph PowerShell cmdlets, REST endpoints, permissions and modules using the shared GraphShell catalog. .DESCRIPTION Get-GraphMapping is the main entry point of the GraphShell module. Unlike a single cmdlet-to-endpoint lookup, it lets you enter the GraphShell catalog from any of five angles (cmdlet, endpoint, permission, module or free-text query) and returns the relationships GraphShell already knows about that entry point: HTTP method, API version, aliases, variants and, on request, permissions/output type/documentation. GraphShell does not call the Microsoft Graph API or your tenant. It only reads the static catalog generated by scripts/sync-graph-command-index.ps1, the same catalog used by the GraphShell Explorer web app. .PARAMETER Cmdlet A Microsoft Graph PowerShell SDK cmdlet name, for example "Get-MgUser". Also resolves official cmdlet aliases and, when the cmdlet was renamed by the SDK, the current name. .PARAMETER Endpoint A Microsoft Graph REST endpoint/path, for example "/users" or "/roleManagement/directory/roleEligibilityScheduleInstances". Falls back to a partial match when there is no exact endpoint in the catalog. .PARAMETER Permission A Microsoft Graph permission name, for example "User.Read.All". Uses the graph-command-permissions.json reverse index to return every cmdlet/endpoint associated with that permission, instead of describing the permission itself. .PARAMETER Module A Microsoft.Graph SDK module name (full or partial), for example "Microsoft.Graph.Users" or "Users". .PARAMETER Query A free-text search across cmdlet, endpoint, module and permission names, for concepts you don't yet know the exact cmdlet/endpoint for, for example "PIM eligible". No AI or external service is used; matching is local, token-based scoring over the catalog. .PARAMETER IncludeDetails Also loads the matching detail shard(s) to include Permissions, OutputType, ApiReferenceLink and CommandAlias. Off by default to keep broad searches (Module, Query, Permission) fast, since it can trigger loading several detail shards. .EXAMPLE Get-GraphMapping -Cmdlet "Get-MgUser" Looks up a known cmdlet and returns its HTTP method, endpoint, API version, aliases and variants from the GraphShell catalog. .EXAMPLE Get-GraphMapping -Endpoint "/users" Looks up a known Graph REST endpoint and returns every cmdlet that maps to it. .EXAMPLE Get-GraphMapping -Permission "User.Read.All" | Select-Object Cmdlet, Method, Endpoint Starts from a permission and lists every cmdlet/endpoint that requires it, using the catalog's permission reverse index instead of describing the permission itself. .EXAMPLE Get-GraphMapping -Module "Microsoft.Graph.Users" Lists every cmdlet that belongs to a Microsoft.Graph SDK module. .EXAMPLE Get-GraphMapping -Query "PIM eligible" Searches cmdlet, endpoint, module, alias and permission names for a concept you don't yet know the exact cmdlet/endpoint for, and returns the best-ranked catalog matches. No AI/LLM or network call is used. .EXAMPLE Get-GraphMapping -Cmdlet "Get-MgUser" -IncludeDetails | Select-Object -ExpandProperty Permissions Also loads the matching detail shard to expand the full permission list for the cmdlet. .OUTPUTS GraphShell.Mapping #> [CmdletBinding(DefaultParameterSetName = 'None')] [OutputType('GraphShell.Mapping')] param( [Parameter(ParameterSetName = 'Cmdlet', Position = 0)] [ValidateNotNullOrEmpty()] [string]$Cmdlet, [Parameter(ParameterSetName = 'Endpoint')] [ValidateNotNullOrEmpty()] [string]$Endpoint, [Parameter(ParameterSetName = 'Permission')] [ValidateNotNullOrEmpty()] [string]$Permission, [Parameter(ParameterSetName = 'Module')] [ValidateNotNullOrEmpty()] [string]$Module, [Parameter(ParameterSetName = 'Query')] [ValidateNotNullOrEmpty()] [string]$Query, [switch]$IncludeDetails ) if ($PSCmdlet.ParameterSetName -eq 'None') { Write-Warning ( "Get-GraphMapping needs one entry point into the GraphShell catalog. Use exactly one of:`n" + " -Cmdlet <name> e.g. Get-GraphMapping -Cmdlet Get-MgUser`n" + " -Endpoint <path> e.g. Get-GraphMapping -Endpoint /users`n" + " -Permission <name> e.g. Get-GraphMapping -Permission User.Read.All`n" + " -Module <name> e.g. Get-GraphMapping -Module Microsoft.Graph.Users`n" + " -Query <text> e.g. Get-GraphMapping -Query 'PIM eligible'`n" + "See Get-Help Get-GraphMapping -Full for details." ) return } $params = @{ IncludeDetails = $IncludeDetails } switch ($PSCmdlet.ParameterSetName) { 'Cmdlet' { $params['Cmdlet'] = $Cmdlet } 'Endpoint' { $params['Endpoint'] = $Endpoint } 'Permission' { $params['Permission'] = $Permission } 'Module' { $params['Module'] = $Module } 'Query' { $params['Query'] = $Query } } $results = Resolve-GraphMapping @params if (-not $results -or $results.Count -eq 0) { Write-Warning "GraphShell found no mapping in the catalog for -$($PSCmdlet.ParameterSetName) '$($params[$PSCmdlet.ParameterSetName])'." return } return $results } |