使用腳本將使用者新增至 eDiscovery (Standard) 案例中的保留

發行項
01/10/2024

安全性 & 合規性 PowerShell 提供 Cmdlet，可讓您自動化與建立和管理電子檔探索案例相關的耗時工作。目前，在 Microsoft Purview 合規性入口網站中使用 Microsoft Purview 電子文件探索 (Standard) 案例來保留大量監管人內容位置需要時間和準備。例如，在建立保留之前，您必須收集您想要保留之每個商務用 OneDrive 網站的 URL。然後，針對您想要保留的每個使用者，您必須將其信箱和其商務用 OneDrive 網站新增至保留。您可以使用本文中的腳本來自動化此程式。

腳本會提示您輸入貴組織的「我的網站」網域名稱 (例如， contoso 在 URL https://contoso-my.sharepoint.com) 、現有電子檔探索案例的名稱、與案例相關聯的新保留名稱、您想要保留之使用者的電子郵件地址清單，以及如果您想要建立查詢架構的保留，則要使用的搜尋查詢。腳本接著會取得清單中每個使用者的商務用 OneDrive 網站 URL、建立新的保留，然後將清單中每個使用者的信箱和商務用 OneDrive 網站新增至保留。腳本也會產生包含新保留信息的記錄檔。

以下是進行此作業的步驟：

步驟 1：安裝 SharePoint Online 管理命令介面步驟 2：產生使用者清單步驟 3：執行腳本來建立保留並新增使用者

提示

如果您不是 E5 客戶，請使用 90 天的 Microsoft Purview 解決方案試用版來探索其他 Purview 功能如何協助貴組織管理數據安全性與合規性需求。立即從 Microsoft Purview 合規性入口網站試用中樞開始。瞭解有關註冊和試用版條款的詳細數據。

將使用者新增至保留之前

您必須是合規性入口網站中電子檔探索管理員角色群組的成員，以及 SharePoint Online 系統管理員，才能在步驟 3 中執行腳本。如需詳細資訊，請參閱 Office 365 Security & Compliance Center 中的指派電子檔探索許可權。
最多可以將 1,000 個信箱和 100 個網站新增至與合規性入口網站中電子檔探索案例相關聯的保留。假設您想要保留的每個使用者都有商務用 OneDrive 網站，您可以使用本文中的腳本，將最多 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 網站。
本主題中提供的範例腳本不支援任何 Microsoft 標準支援計劃或服務。範例指令碼係依「現狀」提供，不含任何種類的擔保方式。 Microsoft 另外不承擔任何明示或默示的擔保，包括但不限於適售性或適合某特定用途的默示擔保。使用或操作範例指令碼和文件發生的所有風險，皆屬於您的責任。 Microsoft、其作者以及其他與建置、生產或交付程式碼相關的任何人在任何情況下皆完全不需對任何損失負責任，包括但不限於商業利潤損失、業務中斷、業務資訊損失、或其他錢財損失等因使用或無法使用範例指令碼或文件所發生的損失，即使 Microsoft 曾建議這些損失發生的可能性。

步驟 1：安裝 SharePoint Online 管理命令介面

如果 SharePoint Online 管理命令介面尚未安裝在本機電腦上，則第一個步驟是安裝它。您不需要在此程式中使用殼層，但必須安裝它，因為它包含您在步驟 3 中執行的腳本所需的必要條件。這些必要條件可讓腳本與 SharePoint Online 通訊，以取得商務用 OneDrive 網站的 URL。

移至設定 SharePoint Online 管理命令介面環境，然後執行步驟 1 和步驟 2，在本機電腦上安裝 SharePoint Online 管理命令介面。

步驟 2：產生使用者清單

步驟 3 中的文稿會建立與電子檔探索案例相關聯的保留，並將使用者清單的信箱和商務用 OneDrive 網站新增至保留。您可以直接在文本檔中輸入電子郵件位址，也可以在 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 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
```
輸入文稿提示您的資訊。

腳本會連線到安全性 & 合規性 PowerShell，然後在電子檔探索案例中建立新的保留，並新增清單中使用者的信箱和商務用 OneDrive。您可以在合規性入口網站的 電子檔探索 頁面上移至案例，以檢視新的保留。

腳本執行完成之後，它會建立下列記錄檔，並將它們儲存到腳本所在的資料夾。

LocationsOnHold.txt：包含腳本成功保留的信箱和商務用 OneDrive 網站清單。
LocationsNotOnHold.txt：包含文稿未保留的信箱和商務用 OneDrive 網站清單。如果使用者有信箱，但沒有商務用 OneDrive 網站，則使用者會包含在未保留的商務用 OneDrive 網站清單中。
GetCaseHoldPolicy.txt： 包含新保留的 Get-CaseHoldPolicy Cmdlet 輸出，腳本會在建立新的保留之後執行。此 Cmdlet 傳回的資訊包含信箱和商務用 OneDrive 網站被保留，以及是否啟用或停用保留的用戶清單。
GetCaseHoldRule.txt： 包含新保留的 Get-CaseHoldRule Cmdlet 輸出，腳本會在建立新的保留之後執行。如果您使用腳本來建立查詢式保留，此 Cmdlet 所傳回的資訊會包含搜尋查詢。

共用方式為