在电子数据展示 (Standard) 案例中使用脚本将用户添加到保留

项目
12/18/2024

提示

电子数据展示 (预览) 现已在新的 Microsoft Purview 门户中提供。若要详细了解如何使用新的电子数据展示体验，请参阅了解电子数据展示 (预览版) 。

安全性 & 合规性 PowerShell 提供 cmdlet，使你可以自动执行与创建和管理电子数据展示案例相关的耗时任务。目前，在Microsoft Purview 合规门户中使用Microsoft Purview 电子数据展示 (Standard) 案例将大量保管人内容位置置于保留状态需要时间和准备。例如，在创建保留之前，必须收集要保留的每个OneDrive for Business网站的 URL。然后，对于要保留的每个用户，你必须将其邮箱和OneDrive for Business网站添加到保留。可以使用本文中的脚本自动执行此过程。

该脚本会提示输入组织的“我的网站”域的名称 (例如， contoso 在 URL https://contoso-my.sharepoint.com) 、现有电子数据展示事例的名称、与案例关联的新保留的名称、要保留的用户的电子邮件地址列表，以及要创建基于查询的保留时要使用的搜索查询。然后，该脚本获取列表中每个用户OneDrive for Business网站的 URL，创建新的保留，然后将列表中的每个用户的邮箱和OneDrive for Business网站添加到保留。该脚本还会生成包含有关新保留信息的日志文件。

下面是执行此操作的步骤：

步骤 1：安装SharePoint Online 命令行管理程序步骤 2：生成用户列表步骤 3：运行脚本以创建保留并添加用户

提示

如果你不是 E5 客户，请使用 90 天Microsoft Purview 解决方案试用版来探索其他 Purview 功能如何帮助组织管理数据安全性和合规性需求。立即在 Microsoft Purview 试用中心开始。了解有关注册和试用条款的详细信息。

在将用户添加到保留之前

您必须是合规性门户中电子数据展示管理员角色组的成员和 SharePoint Online 管理员才能在步骤 3 中运行脚本。有关详细信息，请参阅在Office 365安全 & 合规中心分配电子数据展示权限。
最多可将 1,000 个邮箱和 100 个网站添加到与合规性门户中的电子数据展示案例关联的保留。假设要保留的每个用户都有一个OneDrive for Business网站，则可以使用本文中的脚本向保留添加最多 100 个用户。
请务必将步骤 2 中创建的用户列表和步骤 3 中的脚本保存到同一文件夹。这样一来，可以更轻松地运行脚本。
该脚本将用户列表添加到与现有案例关联的新保留。在运行脚本之前，请确保已创建要与保留关联的事例。
本文中的脚本支持在连接到安全性 & 符合性 PowerShell 和 SharePoint Online 命令行管理程序时进行新式身份验证。如果你是 Microsoft 365 或 Microsoft 365 GCC 组织，则可以按原样使用脚本。如果你是Office 365德国组织、Microsoft 365 GCC High 组织或Microsoft 365 DoD 组织，则必须编辑脚本才能成功运行它。具体而言，必须编辑该行 Connect-IPPSSession ，并使用 ConnectionUri 和 AzureADAuthorizationEndpointUri 参数 (以及组织类型) 的相应值来连接到安全性 & 合规性 PowerShell。有关详细信息，请参阅连接到安全性 & 符合性 PowerShell 中的示例。
该脚本会自动断开与安全性 & 合规性 PowerShell 的连接，并SharePoint Online 命令行管理程序。
该脚本包含最少的错误处理。其主要用途是快速轻松地将每个用户的邮箱和OneDrive for Business站点置于保留状态。
任何Microsoft标准支持计划或服务都不支持本主题中提供的示例脚本。示例脚本“原样”提供，不提供任何形式的保证。 Microsoft 进一步拒绝所有默示保证，包括但不限于针对特定用途的适销性或适用性的任何默示保证。由于示例脚本及文档的使用或性能所引起的全部风险均由您承担。在任何情况下，对于由于使用或者无法使用示例脚本或文档所引起的任何损失（包括但不限于商业利润损失、业务中断、商业信息丢失或者其他经济损失），Microsoft、其作者或者参与创建、制作或交付脚本的任何人概不负责，即使 Microsoft 已被告知可能会出现此类损失。

步骤 1：安装 SharePoint Online 命令行管理程序

第一步是安装SharePoint Online 命令行管理程序（如果尚未安装在本地计算机上）。在此过程中，无需使用 shell，但必须安装它，因为它包含步骤 3 中运行的脚本所需的先决条件。这些先决条件允许脚本与 SharePoint Online 通信以获取OneDrive for Business网站的 URL。

转到设置SharePoint Online 命令行管理程序环境，并执行步骤 1 和步骤 2，在本地计算机上安装SharePoint Online 命令行管理程序。

步骤 2：生成用户列表

步骤 3 中的脚本将创建与电子数据展示案例关联的保留，并将用户列表的邮箱和OneDrive for Business网站添加到保留。只需在文本文件中键入电子邮件地址，也可以在 PowerShell 中运行命令来获取电子邮件地址列表，并将其保存到位于步骤 3) 中将脚本保存到的同一文件夹中的文件中 (。

下面是一个Exchange Online PowerShell 命令，用于获取组织中所有用户的电子邮件地址列表，并将其保存到名为 HoldUsers.txt 的文本文件中。

Get-Mailbox -ResultSize unlimited -Filter { RecipientTypeDetails -eq 'UserMailbox'} | Select-Object PrimarySmtpAddress > HoldUsers.txt

运行此命令后，打开文本文件并删除包含属性名称 PrimarySmtpAddress的标头。然后删除除要添加到步骤 3 中创建的保留的用户的电子邮件地址之外的所有电子邮件地址。确保电子邮件地址列表之前或之后没有空白行。

步骤 3：运行脚本以创建保留并添加用户

在此步骤中运行脚本时，它会提示你提供以下信息。在运行脚本之前，请务必准备好此信息。

你的用户凭据： 该脚本将使用凭据连接到安全性 & 合规性 PowerShell。它还将使用这些凭据访问 SharePoint Online 以获取用户列表的OneDrive for Business URL。
SharePoint 域的名称： 该脚本会提示输入此名称，以便它可以连接到 SharePoint 管理中心。它还使用组织中 OneDrive URL 的域名。例如，如果管理中心的 URL 为 https://contoso-admin.sharepoint.com ，而 OneDrive 的 URL 为 https://contoso-my.sharepoint.com，则在 contoso 脚本提示输入域名时输入。
案例名称： 现有事例的名称。该脚本将创建与此案例关联的新保留。
保留的名称： 脚本将创建并与指定大小写关联的保留的名称。
基于查询的保留的搜索查询： 可以创建基于查询的保留，以便仅保留满足指定搜索条件的内容。若要保留所有内容，只需在系统提示进行搜索查询时按 Enter 。
启用或不启用保留： 可以在创建脚本后启用保留，也可以让脚本在不启用保留的情况下创建保留。如果没有启用保留的脚本，则可以稍后在合规性门户中或通过运行以下 PowerShell 命令将其打开：
```
Set-CaseHoldPolicy -Identity <name of the hold> -Enabled $true
```
```
Set-CaseHoldRule -Identity <name of the hold> -Disabled $false
```
包含用户列表的文本文件 的名称 - 步骤 2 中包含要添加到保留的用户列表的文本文件的名称。如果此文件与脚本位于同一文件夹中，只需键入文件名 (例如，HoldUsers.txt) 。如果文本文件位于另一个文件夹中，请键入该文件的完整路径名。

收集脚本将提示你输入的信息后，最后一步是运行脚本以创建新的保留并向其添加用户。

使用文件名后缀.ps1将以下文本保存到Windows PowerShell脚本文件。例如，AddUsersToHold.ps1。

#script begin
" "
write-host "***********************************************"
write-host "   Security & Compliance PowerShell  " -foregroundColor yellow -backgroundcolor darkgreen
write-host "   eDiscovery (Standard) cases - Add users to a hold   " -foregroundColor yellow -backgroundcolor darkgreen
write-host "***********************************************"
" "
# Connect to Security & Compliance PowerShell using modern authentication
if (!$SccSession)
{
  Import-Module ExchangeOnlineManagement
  Connect-IPPSSession
}

# Get the organization's domain name. We use this to create the SharePoint admin URL and root URL for OneDrive for Business.
""
$mySiteDomain = Read-Host "Enter the domain name for your SharePoint organization. We use this name to connect to SharePoint admin center and for the OneDrive URLs in your organization. For example, 'contoso' in 'https://contoso-admin.sharepoint.com' and 'https://contoso-my.sharepoint.com'"
""

# Connect to PnP Online using modern authentication
Import-Module PnP.PowerShell
Connect-PnPOnline -Url https://$mySiteDomain-admin.sharepoint.com -UseWebLogin

# Load the SharePoint assemblies from the SharePoint Online Management Shell
# To install, go to https://go.microsoft.com/fwlink/p/?LinkId=255251
if (!$SharePointClient -or !$SPRuntime -or !$SPUserProfile)
{
    $SharePointClient = [System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client")
    $SPRuntime = [System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client.Runtime")
    $SPUserProfile = [System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client.UserProfiles")
    if (!$SharePointClient)
    {
        Write-Error "The SharePoint Online Management Shell isn't installed. Please install it from: https://go.microsoft.com/fwlink/p/?LinkId=255251 and then re-run this script."
        return;
    }
}

# Get other required information
do{
$casename = Read-Host "Enter the name of the case"
$caseexists = (get-compliancecase -identity "$casename" -erroraction SilentlyContinue).isvalid
if($caseexists -ne 'True')
{""
write-host "A case named '$casename' doesn't exist. Please specify the name of an existing case, or create a new case and then re-run the script." -foregroundColor Yellow
""}
}While($caseexists -ne 'True')
""
do{
$holdName = Read-Host "Enter the name of the new hold"
$holdexists=(get-caseholdpolicy -identity "$holdname" -case "$casename" -erroraction SilentlyContinue).isvalid
if($holdexists -eq 'True')
{""
write-host "A hold named '$holdname' already exists. Please specify a new hold name." -foregroundColor Yellow
""}
}While($holdexists -eq 'True')
""
$holdQuery = Read-Host "Enter a search query to create a query-based hold, or press Enter to hold all content"
""
$holdstatus = read-host "Do you want the hold enabled after it's created? (Yes/No)"
do{
""
$inputfile = read-host "Enter the name of the text file that contains the email addresses of the users to add to the hold"
""
$fileexists = test-path -path $inputfile
if($fileexists -ne 'True'){write-host "$inputfile doesn't exist. Please enter a valid file name." -foregroundcolor Yellow}
}while($fileexists -ne 'True')
#Import the list of addresses from the txt file.  Trim any excess spaces and make sure all addresses
    #in the list are unique.
  [array]$emailAddresses = Get-Content $inputfile -ErrorAction SilentlyContinue | where {$_.trim() -ne ""}  | foreach{ $_.Trim() }
  [int]$dupl = $emailAddresses.count
  [array]$emailAddresses = $emailAddresses | select-object -unique
  $dupl -= $emailAddresses.count
#Validate email addresses so the hold creation does not run in to an error.
if($emailaddresses.count -gt 0){
write-host ($emailAddresses).count "addresses were found in the text file. There were $dupl duplicate entries in the file." -foregroundColor Yellow
""
Write-host "Validating the email addresses. Please wait..." -foregroundColor Yellow
""
$finallist =@()
foreach($emailAddress in $emailAddresses)
{
if((get-recipient $emailaddress -erroraction SilentlyContinue).isvalid -eq 'True')
{$finallist += $emailaddress}
else {"Unable to find the user $emailaddress"
[array]$excludedlist += $emailaddress}
}
""
#Find user's OneDrive account URL using email address
Write-Host "Getting the URL for each user's OneDrive for Business site." -foregroundColor Yellow
""
$AdminUrl = "https://$mySiteDomain-admin.sharepoint.com"
$mySiteUrlRoot = "https://$mySiteDomain-my.sharepoint.com"
$urls = @()
foreach($emailAddress in $finallist)
{
try
{
$url=Get-PnPUserProfileProperty -Account $emailAddress | Select PersonalUrl
$urls += $url.PersonalUrl
       Write-Host "- $emailAddress => $url"
       [array]$ODadded += $url.PersonalUrl
       }catch {
 Write-Warning "Could not locate OneDrive for $emailAddress"
 [array]$ODExluded += $emailAddress
 Continue }
}
$urls | FL
if(($finallist.count -gt 0) -or ($urls.count -gt 0)){
""
Write-Host "Creating the hold named $holdname. Please wait..." -foregroundColor Yellow
if(($holdstatus -eq "Y") -or ($holdstatus -eq  "y") -or ($holdstatus -eq "yes") -or ($holdstatus -eq "YES")){
New-CaseHoldPolicy -Name "$holdName" -Case "$casename" -ExchangeLocation $finallist -SharePointLocation $urls -Enabled $True | out-null
New-CaseHoldRule -Name "$holdName" -Policy "$holdname" -ContentMatchQuery $holdQuery | out-null
}
else{
New-CaseHoldPolicy -Name "$holdName" -Case "$casename" -ExchangeLocation $finallist -SharePointLocation $urls -Enabled $false | out-null
New-CaseHoldRule -Name "$holdName" -Policy "$holdname" -ContentMatchQuery $holdQuery -disabled $false | out-null
}
""
}
else {"No valid locations were identified. Therefore, the hold wasn't created."}
#write log files (if needed)
$newhold=Get-CaseHoldPolicy -Identity "$holdname" -Case "$casename" -erroraction SilentlyContinue
$newholdrule=Get-CaseHoldRule -Identity "$holdName" -erroraction SilentlyContinue
if(($ODAdded.count -gt 0) -or ($ODExluded.count -gt 0) -or ($finallist.count -gt 0) -or ($excludedlist.count -gt 0) -or ($newhold.isvalid -eq 'True') -or ($newholdrule.isvalid -eq 'True'))
{
Write-Host "Generating output files..." -foregroundColor Yellow
if($ODAdded.count -gt 0){
"OneDrive Locations" | add-content .\LocationsOnHold.txt
"==================" | add-content .\LocationsOnHold.txt
$newhold.SharePointLocation.name | add-content .\LocationsOnHold.txt}
if($ODExluded.count -gt 0){
"Users without OneDrive locations" | add-content .\LocationsNotOnHold.txt
"================================" | add-content .\LocationsNotOnHold.txt
$ODExluded | add-content .\LocationsNotOnHold.txt}
if($finallist.count -gt 0){
" " | add-content .\LocationsOnHold.txt
"Exchange Locations" | add-content .\LocationsOnHold.txt
"==================" | add-content .\LocationsOnHold.txt
$newhold.ExchangeLocation.name | add-content .\LocationsOnHold.txt}
if($excludedlist.count -gt 0){
" "| add-content .\LocationsNotOnHold.txt
"Mailboxes not added to the hold" | add-content .\LocationsNotOnHold.txt
"===============================" | add-content .\LocationsNotOnHold.txt
$excludedlist | add-content .\LocationsNotOnHold.txt}
$FormatEnumerationLimit=-1
if($newhold.isvalid -eq 'True'){$newhold|fl >.\GetCaseHoldPolicy.txt}
if($newholdrule.isvalid -eq 'True'){$newholdrule|Fl >.\GetCaseHoldRule.txt}
}
}
else {"The hold wasn't created because no valid entries were found in the text file."}
""
#Disconnect from SCC PowerShell and PnPOnline

Write-host "Disconnecting from SCC PowerShell and PnP Online" -foregroundColor Yellow
Get-PSSession | Remove-PSSession
Disconnect-PnPOnline

Write-host "Script complete!" -foregroundColor Yellow
""
#script end

在本地计算机上，打开Windows PowerShell并转到保存脚本的文件夹。
运行脚本;例如：
```
.\AddUsersToHold.ps1
```
输入脚本提示输入的信息。

该脚本连接到 Security & Compliance PowerShell，然后在电子数据展示案例中创建新的保留，并为列表中的用户添加邮箱和OneDrive for Business。可以在合规性门户中的 电子数据展示 页上转到案例以查看新的保留。

脚本运行完成后，会创建以下日志文件，并将其保存到脚本所在的文件夹中。

LocationsOnHold.txt：包含脚本成功置于保留状态的邮箱和OneDrive for Business站点的列表。
LocationsNotOnHold.txt：包含脚本未置于保留状态的邮箱和OneDrive for Business站点的列表。如果用户有邮箱，但没有OneDrive for Business网站，该用户将包含在未处于保留状态的OneDrive for Business网站列表中。
GetCaseHoldPolicy.txt： 包含新保留的 Get-CaseHoldPolicy cmdlet 的输出，脚本在创建新保留后运行该输出。此 cmdlet 返回的信息包括其邮箱和OneDrive for Business网站处于保留状态的用户列表，以及是启用或禁用保留。
GetCaseHoldRule.txt： 包含新保留的 Get-CaseHoldRule cmdlet 的输出，该脚本在创建新保留后运行。如果使用脚本创建基于查询的保留，则此 cmdlet 返回的信息包括搜索查询。

通过

在电子数据展示 (Standard) 案例中使用脚本将用户添加到保留

在将用户添加到保留之前

步骤 1：安装 SharePoint Online 命令行管理程序

步骤 2：生成用户列表

步骤 3：运行脚本以创建保留并添加用户

反馈

其他资源