Public/Get-AADGroupByDisplayName.ps1
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 |
<# .NOTES =========================================================================== Created with: SAPIEN Technologies, Inc., PowerShell Studio 2017 v5.4.135 Created on: 2/14/2017 5:53 AM Edited on: 4/22/2017 Created by: Mark Kraus Organization: Filename: Get-AADGroupByDisplayName.ps1 =========================================================================== .DESCRIPTION Get-AADGroupByDisplayName Function #> <# .SYNOPSIS Retrieves an Azure AD Group by the provided Display name .DESCRIPTION Searches Azure Active Directory Graph API for a Group by the provided display name. The provided displayname must be a full case-insensitive match. Partial matches and wildcards are not supported. A MSGraphAPI.DirectoryObject.Group object will be returned for the matching group. Get-AADGroupByDisplayName requires a MSGraphAPI.Oauth.AccessToken issued for the https://graph.windows.net resource. See the Get-GraphOauthAccessToken help for more information. Get-Help -Name Get-GraphOauthAccessToken -Parameter Resource .PARAMETER AccessToken MSGraphAPI.Oauth.AccessToken object obtained from Get-GraphOauthAccessToken. Access Token must be issued for the https://graph.windows.net resource. .PARAMETER DisplayName The Group's Display Name. This must be an exact case-insensitive match and does not support wildcards or partial matches. .PARAMETER BaseURL The Azure AD Graph Base URL. This is not required. Deafult https://graph.windows.net .PARAMETER APIVersion Version of the API to use. Default is 1.6 .EXAMPLE PS C:\> $AADGroup = Get-AADGroupByDisplayName -AccessToken $GraphAccessToken -DisplayName 'Adataum Finance' .OUTPUTS MSGraphAPI.DirectoryObject.Group .LINK http://psmsgraph.readthedocs.io/en/latest/functions/Get-AADGroupByDisplayName .LINK http://psmsgraph.readthedocs.io/en/latest/functions/Get-AADGroupMember .LINK http://psmsgraph.readthedocs.io/en/latest/functions/Get-AADGroupByID .LINK http://psmsgraph.readthedocs.io/en/latest/functions/Get-GraphOauthAccessToken .LINK https://msdn.microsoft.com/en-us/library/azure/ad/graph/api/groups-operations .LINK https://msdn.microsoft.com/en-us/library/azure/ad/graph/howto/azure-ad-graph-api-supported-queries-filters-and-paging-options#filter #> function Get-AADGroupByDisplayName { [CmdletBinding(SupportsShouldProcess = $true, HelpUri = 'http://psmsgraph.readthedocs.io/en/latest/functions/Get-AADGroupByDisplayName')] [OutputType('MSGraphAPI.DirectoryObject.Group')] param ( [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [ValidateNotNullOrEmpty()] [PSTypeName('MSGraphAPI.Oauth.AccessToken')] $AccessToken, [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, ValueFromRemainingArguments = $true)] [ValidateNotNullOrEmpty()] [string[]]$DisplayName, [Parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true)] [ValidateNotNullOrEmpty()] [string]$BaseUrl = 'https://graph.windows.net', [Parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true)] [ValidateNotNullOrEmpty()] [string]$APIversion = '1.6' ) process { foreach ($GroupName in $DisplayName) { if (-not $pscmdlet.ShouldProcess($ServiceId)) { return } $Application = $AccessToken.Application $Tenant = $Application.Tenant $Url = '{0}/{1}/{2}?api-version={3}&$filter=displayName+eq+%27{4}%27' -f @( $BaseUrl $Tenant 'groups' $APIversion [System.Web.HttpUtility]::UrlEncode($GroupName) ) $Params = @{ Uri = $Url Method = 'GET' AccessToken = $AccessToken ErrorAction = 'Stop' } try { $Result = Invoke-GraphRequest @Params } catch { $ErrorMessage = "Unable to query Group '{0}': {1}" -f $GroupName, $_.Exception.Message Write-Error -Message $ErrorMessage -Exception $_.Exception return } foreach ($ServiceObject in $Result.ContentObject.value) { $OutputObject = $ServiceObject.psobject.copy() $OutputObject.psobject.TypeNames.Insert(0, 'MSGraphAPI.DirectoryObject.Group') $OutputObject | Add-Member -MemberType NoteProperty -Name _AccessToken -Value $AccessToken $OutputObject } } } } |