Usar um script para adicionar usuários a um porão em um caso de descoberta eletrônica (Standard)

Artigo
10/01/2023

Segurança & Conformidade O PowerShell fornece cmdlets que permitem automatizar tarefas demoradas relacionadas à criação e gerenciamento de casos de descoberta eletrônica. Atualmente, o uso do caso Descoberta Eletrônica do Microsoft Purview (Standard) no portal de conformidade do Microsoft Purview para colocar um grande número de locais de conteúdo do custodiante em espera leva tempo e preparação. Por exemplo, antes de criar um porão, você precisa coletar a URL de cada OneDrive for Business site que deseja colocar em espera. Em seguida, para cada usuário que você deseja colocar em espera, você precisa adicionar sua caixa de correio e seu site OneDrive for Business ao porão. Você pode usar o script neste artigo para automatizar esse processo.

O script solicita o nome do domínio My Site da sua organização (por exemplo, contoso na URL https://contoso-my.sharepoint.com), o nome de um caso de descoberta eletrônica existente, o nome do novo hold associado ao caso, uma lista de endereços de email dos usuários que você deseja colocar em espera e uma consulta de pesquisa a ser usada se você quiser criar uma retenção baseada em consulta. Em seguida, o script obtém a URL do site OneDrive for Business para cada usuário na lista, cria o novo hold e adiciona a caixa de correio e OneDrive for Business site para cada usuário na lista ao porão. O script também gera arquivos de log que contêm informações sobre o novo hold.

Aqui estão as etapas para fazer isso acontecer:

Etapa 1: instalar o Shell de Gerenciamento do SharePoint Online Etapa 2: Gerar uma lista de usuários Etapa 3: Executar o script para criar um hold e adicionar usuários

Dica

Se você não for um cliente E5, use a avaliação de soluções do Microsoft Purview de 90 dias para explorar como recursos adicionais do Purview podem ajudar sua organização a gerenciar as necessidades de segurança e conformidade de dados. Comece agora no hub de avaliações portal de conformidade do Microsoft Purview. Saiba mais sobre os termos de inscrição e avaliação.

Antes de adicionar usuários a um porão

Você precisa ser membro do grupo de funções do eDiscovery Manager no portal de conformidade e um administrador do SharePoint Online para executar o script na Etapa 3. Para obter mais informações, consulte Atribuir permissões de descoberta eletrônica na Central de Conformidade & de Segurança Office 365.
No máximo 1.000 caixas de correio e 100 sites podem ser adicionados a um hold associado a um caso de descoberta eletrônica no portal de conformidade. Supondo que cada usuário que você deseja colocar em espera tenha um site OneDrive for Business, você pode adicionar um máximo de 100 usuários a um porão usando o script neste artigo.
Salve a lista de usuários que você cria na Etapa 2 e o script na Etapa 3 para a mesma pasta. Isso facilitará a execução do script.
O script adiciona a lista de usuários a um novo hold associado a um caso existente. Certifique-se de que o caso ao qual você deseja associar a retenção seja criado antes de executar o script.
O script neste artigo dá suporte à autenticação moderna ao se conectar ao Security & Compliance PowerShell e Ao SharePoint Online Management Shell. Você pode usar o script como está se você for um Microsoft 365 ou uma organização do Microsoft 365 GCC. Se você for uma organização Office 365 Alemanha, uma organização do Microsoft 365 GCC High ou uma organização do Microsoft 365 DoD, você terá que editar o script para executá-lo com êxito. Especificamente, você precisa editar a linha Connect-IPPSSession e usar os parâmetros ConnectionUri e AzureADAuthorizationEndpointUri (e os valores apropriados para o tipo de organização) para se conectar ao Security & Compliance PowerShell. Para obter mais informações, confira os exemplos em Conectar-se ao PowerShell de Conformidade do & de Segurança.
O script se desconecta automaticamente do Security & Compliance PowerShell e do SharePoint Online Management Shell.
O script inclui o tratamento mínimo de erros. Sua principal finalidade é colocar rapidamente e facilmente a caixa de correio e OneDrive for Business site de cada usuário em espera.
Os scripts de exemplo fornecidos neste tópico não têm suporte em nenhum programa ou serviço de suporte padrão da Microsoft. Os scripts de exemplo são fornecidos COMO ESTÃO sem qualquer tipo de garantia. A Microsoft também se isenta de todas as garantias implícitas, incluindo sem limitações quaisquer garantias aplicáveis de padrões de comercialização ou de adequação a uma finalidade específica. Todos os riscos decorrentes do uso ou da execução da documentação ou scripts de exemplo serão de sua responsabilidade. De modo algum a Microsoft, seus autores ou qualquer outra pessoa envolvida na criação, produção ou veiculação dos scripts serão considerados responsáveis por quaisquer danos (incluindo sem limitações danos por perda de lucros comerciais, interrupção de negócios, perda de informações comerciais ou outras perdas pecuniárias) resultantes do uso ou da incapacidade de uso da documentação ou scripts de exemplo, mesmo que a Microsoft tenha sido alertada sobre a possibilidade de tais danos.

Etapa 1: Instalar o Shell de gerenciamento do SharePoint Online

A primeira etapa é instalar o Shell de Gerenciamento online do SharePoint se ele ainda não estiver instalado no computador local. Você não precisa usar o shell neste procedimento, mas precisa instalá-lo porque ele contém pré-requisitos exigidos pelo script que você executa na Etapa 3. Esses pré-requisitos permitem que o script se comunique com o SharePoint Online para obter as URLs dos sites OneDrive for Business.

Vá para Configurar o ambiente do Shell de Gerenciamento do SharePoint Online e execute a Etapa 1 e a Etapa 2 para instalar o Shell de Gerenciamento do SharePoint Online em seu computador local.

Etapa 2: gerar uma lista de usuários

O script na Etapa 3 criará um hold associado a um caso de descoberta eletrônica e adicionará as caixas de correio e OneDrive for Business sites de uma lista de usuários ao porão. Basta digitar os endereços de email em um arquivo de texto ou executar um comando no PowerShell para obter uma lista de endereços de email e salvá-los em um arquivo (localizado na mesma pasta na qual você salvará o script na Etapa 3).

Aqui está um Exchange Online comando do PowerShell para obter uma lista de endereços de email para todos os usuários da sua organização e salvá-lo em um arquivo de texto chamado HoldUsers.txt.

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

Depois de executar esse comando, abra o arquivo de texto e remova o cabeçalho que contém o nome da propriedade, PrimarySmtpAddress. Em seguida, remova todos os endereços de email, exceto os dos usuários que você deseja adicionar ao porão que você criará na Etapa 3. Verifique se não há linhas em branco antes ou depois da lista de endereços de email.

Etapa 3: executar o script para criar um hold e adicionar usuários

Ao executar o script nesta etapa, ele solicitará as seguintes informações. Certifique-se de ter essas informações prontas antes de executar o script.

Suas credenciais de usuário: O script usará suas credenciais para se conectar ao PowerShell de Conformidade do & de Segurança. Ele também usará essas credenciais para acessar o SharePoint Online para obter as URLs OneDrive for Business para a lista de usuários.
Nome do domínio do SharePoint: O script solicita que você insira esse nome para que ele possa se conectar ao centro de administração do SharePoint. Ele também usa o nome de domínio para as URLs do OneDrive em sua organização. Por exemplo, se a URL do centro de administração for https://contoso-admin.sharepoint.com e a URL do OneDrive for https://contoso-my.sharepoint.com, você entrará contoso quando o script solicitar seu nome de domínio.
Nome do caso: O nome de um caso existente. O script criará um novo hold associado a esse caso.
Nome da retenção: O nome do hold que o script criará e associará ao caso especificado.
Pesquise uma consulta por um porão baseado em consulta: Você pode criar um hold baseado em consulta para que apenas o conteúdo que atende aos critérios de pesquisa especificados seja colocado em espera. Para colocar todo o conteúdo em espera, basta pressionar Enter quando você for solicitado para uma consulta de pesquisa.
Ativando ou não o porão: Você pode fazer com que o script ative o porão depois que ele for criado ou faça com que o script crie o hold sem habilitá-lo. Se você não tiver o script ativado no porão, poderá ativá-lo mais tarde no portal de conformidade ou executando os seguintes comandos do PowerShell:
```
Set-CaseHoldPolicy -Identity <name of the hold> -Enabled $true
```
```
Set-CaseHoldRule -Identity <name of the hold> -Disabled $false
```
Nome do arquivo de texto com a lista de usuários – o nome do arquivo de texto da Etapa 2 que contém a lista de usuários a serem adicionados ao porão. Se esse arquivo estiver localizado na mesma pasta que o script, basta digitar o nome do arquivo (por exemplo, HoldUsers.txt). Se o arquivo de texto estiver em outra pasta, digite o nome completo do arquivo.

Depois de coletar as informações que o script solicitará, a etapa final é executar o script para criar o novo hold e adicionar usuários a ele.

Salve o texto a seguir em um arquivo de script Windows PowerShell usando um sufixo de nome de arquivo de .ps1. Por exemplo, 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

No computador local, abra Windows PowerShell e vá para a pasta em que você salvou o script.
Execute o script; por exemplo:
```
.\AddUsersToHold.ps1
```
Insira as informações que o script solicita.

O script se conecta ao Security & Compliance PowerShell e cria o novo porão no caso de descoberta eletrônica e adiciona as caixas de correio e OneDrive for Business para os usuários da lista. Você pode acessar o caso na página de descoberta eletrônica no portal de conformidade para exibir o novo hold.

Depois que o script é concluído em execução, ele cria os arquivos de log a seguir e os salva na pasta em que o script está localizado.

LocationsOnHold.txt: Contém uma lista de caixas de correio e OneDrive for Business sites que o script colocou com êxito em espera.
LocationsNotOnHold.txt: Contém uma lista de caixas de correio e OneDrive for Business sites que o script não colocou em espera. Se um usuário tiver uma caixa de correio, mas não um site OneDrive for Business, o usuário será incluído na lista de OneDrive for Business sites que não foram colocados em espera.
GetCaseHoldPolicy.txt: Contém a saída do cmdlet Get-CaseHoldPolicy para o novo hold, que o script executou após a criação do novo hold. As informações retornadas por este cmdlet incluem uma lista de usuários cujas caixas de correio e OneDrive for Business sites foram colocados em espera e se a retenção está habilitada ou desabilitada.
GetCaseHoldRule.txt: Contém a saída do cmdlet Get-CaseHoldRule para o novo hold, que o script executou após a criação do novo hold. As informações retornadas por este cmdlet incluem a consulta de pesquisa se você usou o script para criar uma retenção baseada em consulta.