Skip to content

Commit f1fe827

Browse files
chrisdachrisda
authored
Merge pull request #13299 from anirudhbharadwaj/patch-1
Create Get-AdaptiveScopeMembers.md
2 parents 2dd855f + ea05d5d commit f1fe827

File tree

3 files changed

+345
-1
lines changed

3 files changed

+345
-1
lines changed

‎exchange/exchange-ps/ExchangePowerShell/ExchangePowerShell.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2159,6 +2159,8 @@ Exchange PowerShell is built on PowerShell technology to a powerful command-line
21592159

21602160
### [Get-AdaptiveScope](Get-AdaptiveScope.md)
21612161

2162+
### [Get-AdaptiveScopeMembers](Get-AdaptiveScopeMembers.md)
2163+
21622164
### [Get-AppRetentionCompliancePolicy](Get-AppRetentionCompliancePolicy.md)
21632165

21642166
### [Get-AppRetentionComplianceRule](Get-AppRetentionComplianceRule.md)

‎exchange/exchange-ps/ExchangePowerShell/Get-AdaptiveScopeMembers.md‎

Lines changed: 341 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,341 @@
1+
---
2+
applicable: Exchange Online, Security & Compliance
3+
author: chrisda
4+
external help file: Microsoft.Exchange.TransportMailflow-Help.xml
5+
Locale: en-US
6+
Module Name: ExchangePowerShell
7+
ms.author: chrisda
8+
ms.reviewer: amuralidhara
9+
online version: https://learn.microsoft.com/powershell/module/exchangepowershell/get-adaptivescopemembers
10+
schema: 2.0.0
11+
title: Get-AdaptiveScopeMembers
12+
---
13+
14+
# Get-AdaptiveScopeMembers
15+
16+
## SYNOPSIS
17+
This cmdlet is available only in the cloud-based service.
18+
19+
Use the Get-AdaptiveScopeMembers cmdlet to retrieve current and past members of adaptive scopes in your organization. Adaptive scopes are used in retention policies, Insider Risk Management policies and retention label policies.
20+
21+
For information about the parameter sets in the Syntax section below, see [Exchange cmdlet syntax](https://learn.microsoft.com/powershell/exchange/exchange-cmdlet-syntax).
22+
23+
## SYNTAX
24+
25+
### Identity (Default)
26+
27+
```
28+
Get-AdaptiveScopeMembers [-Identity] <ComplianceRuleIdParameter> [<CommonParameters>]
29+
```
30+
31+
### Default
32+
33+
```
34+
Get-AdaptiveScopeMembers [-Identity] <ComplianceRuleIdParameter>
35+
[-AdaptiveReportFilters <PswsHashtable>]
36+
[-PageResultSize <UnlimitedInt>]
37+
[-State <LocationState>]
38+
[<CommonParameters>]
39+
```
40+
41+
### AdaptiveReportPagination
42+
43+
```
44+
Get-AdaptiveScopeMembers [-Identity] <ComplianceRuleIdParameter> -PageCookie <string> [<CommonParameters>]
45+
```
46+
47+
## DESCRIPTION
48+
49+
Use this cmdlet to retrieve existing and past members (users, groups, or sites) of an adaptive scope.
50+
51+
Cmdlet output is a list where the first element contains result metadata. Subsequent elements contain the members.
52+
53+
Metadata includes the following information:
54+
55+
- The total number of members for the request.
56+
- The number of members returned in the current page.
57+
- Whether additional pages are available.
58+
59+
If additional pages exist, the metadata includes a Watermark value and the IsLastPage value is False.
60+
61+
To retrieve the next page, pass the Watermark value to the PageCookie parameter in your next invocation of the cmdlet. Use the AdaptiveReportFilters parameter to filter the members.
62+
63+
To use this cmdlet in Security & Compliance PowerShell, you need to be assigned permissions. For more information, see [Permissions in the Microsoft Purview compliance portal](https://learn.microsoft.com/purview/microsoft-365-compliance-center-permissions).
64+
65+
## EXAMPLES
66+
67+
### Example 1
68+
```powershell
69+
Get-AdaptiveScopeMembers -Identity "US Finance Users"
70+
```
71+
72+
This example retrieves the members of the adaptive scope US Finance Users. If the scope contains fewer than 10,000 members, all members are returned.
73+
74+
For larger scopes, only the first 10,000 members are included, and the first object in the response contains metadata with a watermark that can be used to request subsequent pages.
75+
76+
### Example 2
77+
```powershell
78+
Get-AdaptiveScopeMembers -Identity "US Finance Users" -PageResultSize Unlimited
79+
```
80+
81+
This example returns every member of the adaptive scope US Finance Users.
82+
83+
**Important**: We don't recommend using the PageResultSize value Unlimited for large adaptive scopes. Using Unlimited on large adaptive scopes might lead to long‑running requests and transient failures that can't be efficiently retried.
84+
85+
### Example 3
86+
```powershell
87+
Get-AdaptiveScopeMembers -Identity "US Finance Users" -PageResultSize 0
88+
```
89+
90+
This example only returns metadata with total member count of the adaptive scope US Finance Users.
91+
92+
### Example 4
93+
```powershell
94+
Get-AdaptiveScopeMembers -Identity "US Finance Users" -PageResultSize 30
95+
```
96+
97+
This example retrieves the members of the adaptive scope US Finance Users. If the scope contains fewer than 30 members, all members are returned.
98+
99+
For larger scopes, only the first 30 members are included, and the first object in the response contains metadata with a watermark that can be used to request subsequent pages.
100+
101+
### Example 5
102+
```powershell
103+
Get-AdaptiveScopeMembers -Identity "US Finance Users" -State Added
104+
```
105+
106+
This example retrieves the current members of the adaptive scope US Finance Users. If the scope contains fewer than 10,000 current members, all current members are returned.
107+
108+
For larger scopes, only the first 10,000 current members are included, and the first object in the response contains metadata with a watermark that can be used to request subsequent pages.
109+
110+
### Example 6
111+
```powershell
112+
Get-AdaptiveScopeMembers -Identity "US Finance Users" -State Removed
113+
```
114+
115+
This example retrieves the past members of the adaptive scope US Finance Users. If the scope contains fewer than 10,000 past members, all past members are returned.
116+
117+
For larger scopes, only the first 10,000 past members are included, and the first object in the response contains metadata with a watermark that can be used to request subsequent pages.
118+
119+
### Example 7
120+
```powershell
121+
Get-AdaptiveScopeMembers -Identity "US Finance Sites" -AdaptivereportFilters @{"SiteUrlContainsAny" = @("/personal/", "/teams/")}
122+
```
123+
124+
This example retrieves the members of the adaptive scope US Finance Sites where the site url contains `/personal/` or `/teams/`. If the results contains fewer than 10,000 members, all are returned.
125+
126+
For larger results, only the first 10,000 are included, and the first object in the response contains metadata with a watermark that can be used to request subsequent pages.
127+
128+
### Example 8
129+
```powershell
130+
$scope="US Finance Users"; $size=200; $cookie=$null
131+
$all=@()
132+
do {
133+
$page = Get-AdaptiveScopeMembers -Identity $scope -Size $size -PageCookie $cookie
134+
if(-not $page){ break }
135+
$meta = $page[0]
136+
if($meta.CurrentPageMemberCount -gt 0){ $all += $page[1..($page.Count-1)] }
137+
$cookie = if($meta.IsLastPage){ $null } else { $meta.Watermark }
138+
} while($cookie -ne $null)
139+
$all | Export-Csv -NoTypeInformation -Path "C:\Data\AdaptiveScopeMembers_$($scope -replace ' ','_').csv"
140+
```
141+
142+
This example retrieves the members of the adaptive scope US Finance Users 200 members at a time and saves them to a list. The results are saved to the specified CSV file.
143+
144+
### Example 9
145+
```powershell
146+
function Export-AdaptiveScopeMembers {
147+
[CmdletBinding()] param([string]$Scope,[string]$Out,[int]$Size=10000,[bool]$Resume=$true)
148+
$scope=$Scope; $out=$Out; $size=$Size;
149+
$meta=Join-Path $out "$scope-exportadaptivescopemembersexecutioninfo.json"
150+
if (-not (Test-Path $out)) { New-Item -ItemType Directory -Path $out | Out-Null }
151+
$m = if ($resume -and (Test-Path $meta)) { Get-Content $meta -Raw | ConvertFrom-Json } else {$null}
152+
$cookie = if ($m) {$m.Watermark} else {$null}; $page = if ($m -and $m.IsLastPage -ne $true) { $m.LastPageProcessed + 1 } else {1}; $isLast=$false
153+
do {
154+
$res = if ($cookie) { Get-AdaptiveScopeMembers -Identity $scope -PageCookie $cookie -WarningAction SilentlyContinue} else { Get-AdaptiveScopeMembers -Identity $scope -PageResultSize $size -WarningAction SilentlyContinue }
155+
$metaObj = $res[0]; $members = $res[1..($res.Count-1)]
156+
if ($members.Count) { $file=Join-Path $out "$scope-part$($page).csv"; $members | Export-Csv $file -NoTypeInformation; Write-Host "Exported $($members.Count) of page $page to file '$file'" }
157+
$cookie = $metaObj.Watermark; $isLast = $metaObj.IsLastPage
158+
$status = @{TimestampUtc=(Get-Date).ToUniversalTime().ToString("o"); TotalResults=$metaObj.TotalMemberCount; PageSize=$metaObj.CurrentPageMemberCount; Identity=$metaObj.Identity; Watermark=$cookie; LastPageProcessed=$page; IsLastPage=$metaObj.IsLastPage}
159+
if ($isLast) {
160+
$status = @{TimestampUtc=(Get-Date).ToUniversalTime().ToString("o"); TotalResults=$metaObj.TotalMemberCount; Identity=$metaObj.Identity; Watermark=$cookie; LastPageProcessed=$page; IsLastPage=$metaObj.IsLastPage}
161+
}
162+
$status | ConvertTo-Json | Set-Content $meta
163+
$page++
164+
} while (-not $isLast)
165+
Write-Host "Completed exporting members of adaptive scope '$scope' to folder '$out'"
166+
}
167+
```
168+
169+
Customers often need to export all members of an adaptive scope into files for review, auditing, offline analysis, or to share with other teams. This **Export‑AdaptiveScopeMembers** helper script simplifies this process by automatically paging through the scope, exporting each page to a CSV file, and writing execution metadata for resume.
170+
171+
This export workflow is **restartable**. If the script stops midway due to a transient failure, network issue, or timeout, you can simply run it again. It reads the existing metadata file, resumes from the last successfully processed page, and continues exporting until all pages have been retrieved.
172+
173+
Paste this function into your session and call it with the desired parameters. You can call `Export-AdaptiveScopeMembers` to save the results to files.
174+
175+
This example retrieves the members of the adaptive scope US Finance Users and saves every 10,000 members to a csv file under the provided folder. The folder is created if it doesn't already exist:
176+
177+
`Export-AdaptiveScopeMembers -Scope "US Finance Users" -Out "D:\adaptivescopedetails"`.
178+
179+
This example retrieves the members of the adaptive scope US Finance Users and saves every 200 members to a csv file under the provided folder. The folder is created if it doesn't already exist:
180+
181+
`Export-AdaptiveScopeMembers -Scope "US Finance Users" -Out "D:\adaptivescopedetails" -Size 200`.
182+
183+
By default, the -Resume parameter is set to $true, allowing the export process to automatically continue from the last completed page if a PowerShell session is interrupted.
184+
Specify $false to start the export from the beginning and overwrite any previously saved progress.
185+
186+
`Export-AdaptiveScopeMembers -Scope "US Finance Users" -Out "D:\adaptivescopedetails" -Size 200 -Resume $false`
187+
188+
## PARAMETERS
189+
190+
### -Identity
191+
192+
> Applicable: Exchange Online, Security & Compliance
193+
194+
The Identity parameter specifies the adaptive scope. You can use any value that uniquely identifies the adaptive scope. For example:
195+
196+
- Name
197+
- Distinguished name (DN)
198+
- GUID
199+
200+
```yaml
201+
Type: ComplianceRuleIdParameter
202+
Parameter Sets: (All)
203+
Aliases:
204+
205+
Required: True
206+
Position: 0
207+
Default value: None
208+
Accept pipeline input: True (ByPropertyName, ByValue)
209+
Accept wildcard characters: False
210+
```
211+
212+
### -AdaptiveReportFilters
213+
214+
> Applicable: Exchange Online, Security & Compliance
215+
216+
The AdaptiveReportFilters parameter specifies one or more filters used to refine the results.
217+
218+
This parameter accepts a hash table where each key maps to a list (array) of up to 10 values. Valid filter keys are:
219+
220+
- MailboxGuidEqualsAny
221+
- MailboxGuidNotEqualsAny
222+
- ObjectIdEqualsAny
223+
- ObjectIdNotEqualsAny
224+
- SiteIdEqualsAny
225+
- SiteIdNotEqualsAny
226+
- SiteUrlContainsAny
227+
- SiteUrlEqualsAny
228+
- SiteUrlNotContainsAny
229+
- SiteUrlNotEqualsAny
230+
- SiteUrlNotStartsWithAny
231+
- SiteUrlStartsWithAny
232+
- SmtpAddressEqualsAny
233+
- SmtpAddressNotEqualsAny
234+
- SmtpAddressNotStartsWithAny
235+
- SmtpAddressStartsWithAny
236+
- UpnEqualsAny
237+
- UpnNotEqualsAny
238+
- UpnNotStartsWithAny
239+
- UpnStartsWithAny
240+
241+
Multiple key values use logical OR syntax. Multiple non-\*Not\* keys use OR syntax. Mixed \*Not\* and non-\*Not\* keys use logical AND syntax.
242+
243+
Example parameter value to filter by UPN prefix:
244+
245+
`@{UpnStartsWithAny = @("john", "mary")`
246+
247+
Example parameter value to include by SMTP address AND exclude by UPN:
248+
249+
`@{SmtpAddressEqualsAny = @("alice@contoso.com","bob@contoso.com"); UpnNotEqualsAny = @("bob.old@contoso.com")}`
250+
251+
Example parameter value to include by SMTP address OR include by UPN
252+
253+
`@{SmtpAddressEqualsAny = @("alice@contoso.com","bob@contoso.com"); UpnEqualsAny = @("bob.old@contoso.com")}`
254+
255+
```yaml
256+
Type: PswsHashtable
257+
Parameter Sets: Default
258+
Aliases:
259+
260+
Required: False
261+
Position: Named
262+
Default value: None
263+
Accept pipeline input: False
264+
Accept wildcard characters: False
265+
```
266+
267+
### -PageCookie
268+
269+
> Applicable: Exchange Online, Security & Compliance
270+
271+
The PageCookie specifies the bookmark where the cmdlet should continue retrieving results from.
272+
273+
Use the Watermark value returned from a previous request to the same adaptive scope as the value of this parameter. The watermark acts as a continuation token, allowing the cmdlet to resume exactly where the previous page ended and fetch the next page of members.
274+
275+
**Important**: Manually editing or fabricating a Watermark value might cause skipped pages, duplicate results, or invalid requests. Always use the Watermark value exactly as returned by the cmdlet.
276+
277+
```yaml
278+
Type: string
279+
Parameter Sets: AdaptiveReportPagination
280+
Aliases:
281+
282+
Required: True
283+
Position: Named
284+
Default value: None
285+
Accept pipeline input: False
286+
Accept wildcard characters: False
287+
```
288+
289+
### -PageResultSize
290+
291+
> Applicable: Exchange Online, Security & Compliance
292+
293+
The PageResultSize parameter specifies the maximum number of members to return for the request.
294+
295+
For best reliability and performance, retrieve members in multiple smaller pages until the last page is reached. This approach introduces natural breakpoints, reduces wait times, and allows seamless retries when transient issues occur.
296+
297+
**Important**: We don't recommend using the PageResultSize value Unlimited for large adaptive scopes. Using Unlimited on large adaptive scopes might lead to long‑running requests and transient failures that can't be efficiently retried.
298+
299+
```yaml
300+
Type: UnlimitedInt
301+
Parameter Sets: Default
302+
Aliases:
303+
304+
Required: False
305+
Position: Named
306+
Default value: 10000
307+
Accept pipeline input: False
308+
Accept wildcard characters: False
309+
```
310+
311+
### -State
312+
313+
> Applicable: Exchange Online, Security & Compliance
314+
315+
The State parameter specifies the state of the members of the adaptive scope. Valid values are:
316+
317+
- Added: Current members of the adaptive scope.
318+
- Removed: Former members of the adaptive scope.
319+
320+
```yaml
321+
Type: LocationState
322+
Parameter Sets: Default
323+
Aliases:
324+
325+
Required: False
326+
Position: Named
327+
Default value: None
328+
Accept pipeline input: False
329+
Accept wildcard characters: False
330+
```
331+
332+
### CommonParameters
333+
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/p/?LinkID=113216).
334+
335+
## INPUTS
336+
337+
## OUTPUTS
338+
339+
## NOTES
340+
341+
## RELATED LINKS

‎exchange/mapping/serviceMapping.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1056,6 +1056,7 @@
10561056
"Export-ContentExplorerData": "policy-and-compliance-retention",
10571057
"Export-FilePlanProperty": "policy-and-compliance-retention",
10581058
"Get-AdaptiveScope": "policy-and-compliance-retention",
1059+
"Get-AdaptiveScopeMembers": "policy-and-compliance-retention",
10591060
"Get-AppRetentionCompliancePolicy": "policy-and-compliance-retention",
10601061
"Get-AppRetentionComplianceRule": "policy-and-compliance-retention",
10611062
"Get-ComplianceRetentionEvent": "policy-and-compliance-retention",
@@ -1418,4 +1419,4 @@
14181419
"Undo-SoftDeletedUnifiedGroup": "users-and-groups",
14191420
"Update-DistributionGroupMember": "users-and-groups",
14201421
"Upgrade-DistributionGroup": "users-and-groups"
1421-
}
1422+
}

0 commit comments

Comments
 (0)