Использование скрипта для добавления пользователей в удержание в случае обнаружения электронных данных (стандартный)

Статья
10/01/2023

Безопасность & соответствия PowerShell предоставляет командлеты, которые позволяют автоматизировать трудоемкие задачи, связанные с созданием случаев обнаружения электронных данных и управлением ими. В настоящее время использование случая Microsoft Purview eDiscovery (стандартный) в Портал соответствия требованиям Microsoft Purview для размещения большого количества расположений хранения содержимого на удержание требует времени и подготовки. Например, перед созданием удержания необходимо получить URL-адрес для каждого OneDrive для бизнеса сайта, который вы хотите поместить на удержание. Затем для каждого пользователя, которого вы хотите поместить на удержание, необходимо добавить его почтовый ящик и OneDrive для бизнеса сайт в удержание. Для автоматизации этого процесса можно использовать скрипт, приведенный в этой статье.

Сценарий запрашивает имя домена личного сайта вашей организации (например, contoso в URL-адресе https://contoso-my.sharepoint.com), имя существующего дела обнаружения электронных данных, имя нового удержания, связанного с делом, список адресов электронной почты пользователей, которые вы хотите поместить на удержание, и поисковый запрос для использования, если вы хотите создать удержание на основе запроса. Затем скрипт получает URL-адрес сайта OneDrive для бизнеса для каждого пользователя в списке, создает новое удержание, а затем добавляет в удержание почтовый ящик и сайт OneDrive для бизнеса для каждого пользователя в списке. Скрипт также создает файлы журналов, содержащие сведения о новом удержании.

Чтобы это произошло, выполните следующие действия.

Шаг 1. Установка командной консоли SharePoint Online Шаг 2. Создание списка пользователей Шаг 3. Запуск сценария для создания удержания и добавления пользователей

Совет

Если вы не являетесь клиентом E5, используйте 90-дневную пробную версию решений Microsoft Purview, чтобы узнать, как дополнительные возможности Purview могут помочь вашей организации управлять безопасностью данных и соответствием требованиям. Начните сейчас, перейдя в центр пробных версий на портале соответствия требованиям Microsoft Purview. Сведения о регистрации и условиях пробной версии.

Перед добавлением пользователей в удержание

Чтобы запустить сценарий на шаге 3, необходимо быть членом группы ролей диспетчера электронных данных на портале соответствия требованиям и администратором SharePoint Online. Дополнительные сведения см. в статье Назначение разрешений на обнаружение электронных данных в Центре соответствия требованиям Office 365 безопасности &.
В удержание можно добавить не более 1000 почтовых ящиков и 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 для бизнеса сайте каждого пользователя на удержание.
Примеры скриптов, приведенные в этом разделе, не поддерживаются ни в одной стандартной программе или службе поддержки Майкрософт. Примеры сценариев приводятся "как есть", без каких-либо гарантий. Кроме того, корпорация Майкрософт отказывается от всех подразумеваемых гарантий, включая, но не ограничиваясь указанным, все подразумеваемые гарантии пригодности для продажи или определенной цели. Все риски, возникающие в результате использования примеров сценариев и документации, берет на себя пользователь. Корпорация Майкрософт, ее штатные авторы и другие лица, принимающие участие в создании, подготовке и выпуске сценариев, ни при каких обстоятельствах не несут ответственность за какой-либо ущерб (в том числе, ущерб, вызванный потерей доходов предприятия, остановкой его работы, потерей бизнес-данных и другими материальными потерями), вызванный использованием или неспособностью использовать примеры сценариев и документацию, даже если корпорации Майкрософт известно о возможности нанесения такого ущерба.

Шаг 1. Установка командной консоли SharePoint Online

Первым шагом является установка командной консоли SharePoint Online, если она еще не установлена на локальном компьютере. В этой процедуре не нужно использовать оболочку, но ее необходимо установить, так как она содержит предварительные требования, необходимые для скрипта, выполняемого на шаге 3. Эти предварительные требования позволяют скрипту взаимодействовать с SharePoint Online, чтобы получить URL-адреса для OneDrive для бизнеса сайтов.

Перейдите в раздел Настройка среды оболочки управления SharePoint Online и выполните шаги 1 и 2, чтобы установить консоль управления SharePoint Online на локальном компьютере.

Шаг 2. Создание списка пользователей

Скрипт на шаге 3 создаст удержание, связанное с делом обнаружения электронных данных, и добавит почтовые ящики и OneDrive для бизнеса сайты списка пользователей в удержание. Вы можете просто ввести адреса электронной почты в текстовом файле или выполнить команду в PowerShell, чтобы получить список адресов электронной почты и сохранить их в файл (расположен в той же папке, в которой вы сохраните скрипт на шаге 3).

Ниже приведена команда PowerShell Exchange Online, чтобы получить список адресов электронной почты для всех пользователей в организации и сохранить его в текстовый файл с именем 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. Он также использует доменное имя для URL-адресов OneDrive в вашей организации. Например, если URL-адрес центра администрирования — , https://contoso-admin.sharepoint.com а URL-адрес для OneDrive — https://contoso-my.sharepoint.com, то следует ввести contoso , когда скрипт запрашивает доменное имя.
Имя дела: Имя существующего дела. Скрипт создаст новое удержание, связанное с этим делом.
Имя удержания: Имя удержания скрипт создаст и свяжет с указанным случаем.
Запрос поиска для удержания на основе запроса: Вы можете создать удержание на основе запроса, чтобы только содержимое, соответствующее указанным условиям поиска, помещалось на удержание. Чтобы поместить все содержимое на удержание, просто нажмите клавишу ВВОД , когда вам будет предложено ввести поисковый запрос.
Включить удержание или нет: Скрипт может включить удержание после его создания или создать удержание, не включив его. Если скрипт не включает удержание, его можно включить позже на портале соответствия требованиям или выполнив следующие команды PowerShell:
```
Set-CaseHoldPolicy -Identity <name of the hold> -Enabled $true
```
```
Set-CaseHoldRule -Identity <name of the hold> -Disabled $false
```
Имя текстового файла со списком пользователей — имя текстового файла из шага 2, содержащего список пользователей для добавления в удержание. Если этот файл находится в той же папке, что и скрипт, просто введите имя файла (например, HoldUsers.txt). Если текстовый файл находится в другой папке, введите полный путь к файлу.

После сбора сведений, которые запрашивает скрипт, последним шагом является запуск скрипта, чтобы создать новый удержание и добавить в него пользователей.

Сохраните следующий текст в файл скрипта Windows PowerShell с помощью суффикса .ps1имени файла . Например, 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 для бизнеса для пользователей в списке. Вы можете перейти к делу на странице eDiscovery на портале соответствия требованиям, чтобы просмотреть новое удержание.

После завершения выполнения скрипт создает следующие файлы журнала и сохраняет их в папку, в которой находится скрипт.

LocationsOnHold.txt: Содержит список почтовых ящиков и OneDrive для бизнеса сайтов, которые скрипт успешно удерживает.
LocationsNotOnHold.txt: Содержит список почтовых ящиков и OneDrive для бизнеса сайтов, которые скрипт не помещал на удержание. Если у пользователя есть почтовый ящик, но не сайт OneDrive для бизнеса, он будет включен в список OneDrive для бизнеса сайтов, которые не были помещены на удержание.
GetCaseHoldPolicy.txt: Содержит выходные данные командлета Get-CaseHoldPolicy для нового удержания, который скрипт выполнял после создания нового удержания. Сведения, возвращаемые этим командлетом, включают список пользователей, чьи почтовые ящики и OneDrive для бизнеса сайты были помещены на удержание, а также сведения о том, включено или отключено ли удержание.
GetCaseHoldRule.txt: Содержит выходные данные командлета Get-CaseHoldRule для нового удержания, который был запущен скриптом после создания нового удержания. Сведения, возвращаемые этим командлетом, включают поисковый запрос, если вы использовали скрипт для создания удержания на основе запроса.