functions/exchange/category/Get-MgaExchCategory.ps1
|
function Get-MgaExchCategory { <# .SYNOPSIS Retrieves categories in Exchange Online using the graph api. .DESCRIPTION Retrieves categories in Exchange Online using the graph api. .PARAMETER InputObject Carrier object for Pipeline input.Accepts CategoryObjects and strings. .PARAMETER Id The Id to filter by. (Client Side filtering) .PARAMETER Name The name to filter by. (Client Side filtering) .PARAMETER Color The color to filter by. (Client Side filtering) Tab completion is available on this parameter for the list of the 25 predefined colors. .PARAMETER User The user-account to access. Defaults to the main user connected as. Can be any primary email name of any user the connected token has access to. .PARAMETER ResultSize The user to execute this under. Defaults to the user the token belongs to. .PARAMETER Token The token representing an established connection to the Microsoft Graph Api. Can be created by using New-MgaAccessToken. Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken. .EXAMPLE PS C:\> Get-MgaExchCategory Return all categories of the user connected to through a token. .EXAMPLE PS C:\> Get-MgaExchCategory -Id "89101089-690d-4263-9470-b674e709a996" Return the category with the specified Id of the user connected to through a token. .EXAMPLE PS C:\> Get-MgaExchCategory -Name "*category" Return all categories with names like "*category" of the user connected to through a token. .EXAMPLE PS C:\> Get-MgaExchCategory -Color "Blue" Return all categories with names like "*category" of the user connected to through a token. #> [CmdletBinding(ConfirmImpact = 'Low', DefaultParameterSetName = 'Default')] [OutputType([MSGraph.Exchange.Category.OutlookCategory])] param ( [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, Position = 0, ParameterSetName = 'ByInputOBject')] [Alias('Category')] [MSGraph.Exchange.Category.CategoryParameter[]] $InputObject, [Parameter(Mandatory = $true, Position = 0, ParameterSetName = 'ById')] [Alias('IdFilter', 'FilterId')] [guid[]] $Id, [Parameter(Mandatory = $true, Position = 0, ParameterSetName = 'ByName')] [Alias('NameFilter', 'FilterName')] [string[]] $Name, [Parameter(Mandatory = $true, Position = 0, ParameterSetName = 'ByColor')] [Alias('ColorFilter', 'FilterColor')] [MSGraph.Exchange.Category.ColorName[]] $Color, [string] $User, [Int64] $ResultSize = (Get-PSFConfigValue -FullName 'MSGraph.Query.ResultSize' -Fallback 100), [MSGraph.Core.AzureAccessToken] $Token ) begin { $requiredPermission = "MailboxSettings.Read" $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand } process { #region query data $invokeParam = @{ "Token" = $Token "User" = $User "ResultSize" = $ResultSize "FunctionName" = $MyInvocation.MyCommand } $data = @() if ($PSCmdlet.ParameterSetName -like 'ByInputOBject') { foreach ($categoryItem in $InputObject) { #region checking input object type and query message if required if ($categoryItem.TypeName -like "System.String") { $categoryItem = Resolve-MailObjectFromString -Object $categoryItem -User $User -Token $Token -FunctionName $MyInvocation.MyCommand if (-not $categoryItem) { continue } } $User = Resolve-UserInMailObject -Object $categoryItem -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand #endregion checking input object type and query message if required $invokeParam.Add("Field", "outlook/masterCategories/$($categoryItem.Id)") Write-PSFMessage -Level Verbose -Message "Get refresh on category '$($categoryItem)'" -Tag "QueryData" $data = $data + (Invoke-MgaRestMethodGet @invokeParam) $invokeParam.Remove("Field") } } else { $invokeParam.Add("Field", "outlook/masterCategories") Write-PSFMessage -Level Verbose -Message "Getting available categories" -Tag "QueryData" $data = $data + (Invoke-MgaRestMethodGet @invokeParam) } #endregion query data #region filter data switch ($PSCmdlet.ParameterSetName) { 'ById' { $data = foreach ($filter in $Id) { Write-PSFMessage -Level VeryVerbose -Message "Filtering on id '$($filter)'." -Tag "FilterData" $data | Where-Object Id -like $filter.Guid } } 'ByName' { $data = foreach ($filter in $Name) { Write-PSFMessage -Level VeryVerbose -Message "Filtering on name '$($filter)'." -Tag "FilterData" $data | Where-Object displayname -like $filter } } 'ByColor' { $data = foreach ($filter in $Color) { Write-PSFMessage -Level VeryVerbose -Message "Filtering on color '$($filter)'." -Tag "FilterData" $data | Where-Object Color -like ([MSGraph.Exchange.Category.OutlookCategory]::Parse($filter)) } } Default {} } #endregion filter data #region output data Write-PSFMessage -Level VeryVerbose -Message "Output $( ($data | Measure-Object).Count ) objects." -Tag "OutputData" foreach ($output in $data) { if ($output.User) { $User = $output.User } $categoryObject = [MSGraph.Exchange.Category.OutlookCategory]::new( $output.id, $output.displayName, $output.color, $User, $output) Write-PSFMessage -Level Debug -Message "Output new object '$($categoryObject)'." -Tag "OutputData" $categoryObject } #endregion output data } end { } } |