スクリプトを使用して Office 365 セキュリティ/コンプライアンス センターの電子情報開示ケースの保留リストにユーザーを追加する

Office 365 セキュリティ/コンプライアンス センターで提供されている多くの Windows PowerShell コマンドレットを使うと、電子情報開示ケースの作成と管理に関連する時間のかかるタスクを自動化できます。現在は、セキュリティ/コンプライアンス センターの電子情報開示ケース ツールを使って多数のカストディアン コンテンツの場所を保留にするには、時間と準備を要します。たとえば、保留リストを作成する前に、保留にする各 OneDrive for Business サイトの URL を収集する必要があります。その後、保留にするユーザーごとに、メールボックスと OneDrive for Business サイトを保留リストに追加する必要があります。セキュリティ/コンプライアンス センターの将来のリリースでは、この作業がより簡単になります。それまでは、この記事に示されているスクリプトを使って、このプロセスを自動化することができます。

スクリプトでは、組織の MySite ドメインの名前 (たとえば、https://contoso-my.sharepoint.com という URL では contoso)、既存の eDiscovery ケースの名前、ケースに関連付ける新しい保留リストの名前、保留にするユーザーのメール アドレスのリスト、およびクエリ ベースの保留リストを作成する場合に使う検索クエリの指定を求められます。その後、スクリプトは、リスト内の各ユーザーの OneDrive for Business サイトの URL を取得し、新しい保留リストを作成した後、リスト内の各ユーザーのメールボックスと OneDrive for Business サイトを保留リストに追加します。また、スクリプトは、新しい保留リストに関する情報を含むログ ファイルも生成します。

そのための手順を以下に示します。

手順 1: SharePoint Online 管理シェルをインストールする

手順 2: ユーザーのリストを生成する

手順 3: スクリプトを実行して保留リストを作成し、ユーザーを追加する

始める前に

  • 手順 3 でスクリプトを実行するには、セキュリティ/コンプライアンス センターの電子情報開示マネージャーの役割グループのメンバーであり、さらに SharePoint Online のグローバル管理者である必要があります。詳細については、「Office 365 のセキュリティとコンプライアンス センターでの電子情報開示の権限を割り当てる」を参照してください。

  • セキュリティ/コンプライアンス センターで電子情報開示ケースに関連付けられている保留リストに追加できるのは、最大で 1,000 メールボックスおよび 100 サイトです。保留にするすべてのユーザーが OneDrive for Business サイトを持っているとすると、この記事のスクリプトを使って、最大 100 ユーザーを保留リストに追加できます。

  • 手順 2 で作成するユーザーのリストと手順 3 のスクリプトは、必ず、同じフォルダーに保存してください。そうすれば、スクリプトをより簡単に実行できます。

  • スクリプトは、既存のケースに関連付けられた新しい保留リストにユーザーのリストを追加します。スクリプトを実行する前に、保留リストを関連付けるケースを作成しておく必要があります。

  • スクリプトには最低限のエラー処理が含まれています。スクリプトの主な目的は、各ユーザーのメールボックスと OneDrive for Business サイトをすばやく簡単に保留にすることです。

  • このトピックに記載されているサンプル スクリプトは、Microsoft の標準的なサポート プログラムやサービスではサポートされていません。サンプル スクリプトはいかなる保障もない現状有姿のままで提供されます。さらに、Microsoft は、商品性、特定目的への適合性を含む一切の黙示の保証をいたしかねます。本サンプル スクリプトおよびドキュメントの使用または性能に起因するすべてのリスクは、お客様が負うものとします。Microsoft、本サンプル スクリプトの作成者、および本スクリプトの作成、製造、配布に関与する者は、いかなる場合においても、本サンプル スクリプトおよびドキュメントの使用または使用不能から生じる損害 (逸失利益、事業の中断、事業情報の喪失またはその他の金銭的損失を含みますがこれらに限定されません) に関して一切責任を負いません。たとえ、Microsoft がこのような損害の可能性について知らされていた場合でも同様です。

先頭に戻る

手順 1: SharePoint Online 管理シェルをインストールする

最初の手順では、SharePoint Online 管理シェルがローカル コンピューターにまだインストールされていない場合は、インストールします。この手順ではシェルを使用する必要はありませんが、手順 3 で実行するスクリプトで必要な前提条件が含まれているため、インストールする必要があります。これらの前提条件を満たすことで、スクリプトを使って SharePoint Online と通信し、OneDrive for Business サイトの URL を取得できるようになります。

SharePoint Online 管理シェルをローカル コンピューターにインストールする場合は、「SharePoint Online 管理シェル Windows PowerShell 環境を設定する」に移動し、手順 1 と手順 2 を実行します。

先頭に戻る

手順 2: ユーザーのリストを生成する

手順 3 のスクリプトでは、電子情報開示ケースと関連付けられた保留リストが作成され、ユーザー リストのメールボックスと OneDrive for Business サイトが保留リストに追加されます。単にテキスト ファイルにメール アドレスを入力するか、Windows PowerShell でコマンドを実行してメール アドレスのリストを取得して、(手順 3 でスクリプトを保存するのと同じフォルダーにある) ファイルに保存することができます。

以下は、組織内のすべてのユーザーのメール アドレスのリストを取得して、HoldUsers.txt という名前のテキスト ファイルに保存するための PowerShell コマンド (Exchange Online 組織に接続されているリモート PowerShell を使って実行します) です。

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

このコマンドを実行した後、テキスト ファイルを開き、PrimarySmtpAddress というプロパティ名を含むヘッダーを削除します。その後、手順 3 で作成する保留リストに追加するユーザーのものを除くすべてのメール アドレスを削除します。メール アドレスのリストの前後に空白行がないことをご確認ください。

先頭に戻る

手順 3: スクリプトを実行して保留リストを作成し、ユーザーを追加する

この手順のスクリプトを実行すると、次の情報の入力を求められます。スクリプトを実行する前に、必ず、この情報を用意しておいてください。

  • ユーザーの資格情報   スクリプトは、ユーザーの資格情報を使って、リモート PowerShell でセキュリティ/コンプライアンス センターに接続します。また、これらの資格情報を使って SharePoint Online にアクセスし、リストのユーザーの OneDrive for Business URL を取得します。

  • 自分の MySite ドメインの名前   MySite ドメインは、組織内のすべての OneDrive for Business サイトを含むドメインです。たとえば、MySite ドメインの URL が https://contoso-my.sharepoint.com の場合、スクリプトで MySite ドメインの名前の入力を求められたときに「contoso」と入力します。

  • ケースの名前   既存のケースの名前です。スクリプトでは、このケースに関連付けられた新しい保留リストが作成されます。

  • 保留リストの名前   スクリプトによって作成され、指定したケースと関連付けられる保留リストの名前です。

  • クエリに基づく保留リストの検索クエリ   クエリに基づく保留リストを作成し、指定した検索条件に一致するコンテンツのみを保留にすることができます。すべてのコンテンツを保留にするには、検索クエリの入力を求められたときに単に Enter キーを押します。

  • 保留リストを有効にするかどうか   スクリプトによって作成された保留リストを有効にするか、または作成するだけで有効にしないかを指定できます。スクリプトで保留リストを有効にしない場合は、後でセキュリティ/コンプライアンス センターを使って、または次の PowerShell コマンドを実行して、有効にできます。

    Set-CaseHoldPolicy -Identity <name of the hold> -Enabled $true
    Set-CaseHoldRule -Identity <name of the hold> -Disabled $false
  • ユーザーのリストを含むテキスト ファイルの名前   保留リストに追加するユーザーのリストが含まれる、手順 2 で作成したテキスト ファイルの名前です。このファイルがスクリプトと同じフォルダーに保存されている場合は、ファイルの名前だけ (たとえば、HoldUsers.txt) を入力します。テキスト ファイルが別のフォルダーにある場合は、ファイルのフル パス名を入力します。

スクリプトで入力を求められる情報を収集した後、最後の手順では、スクリプトを実行して新しい保留リストを作成し、ユーザーを追加します。

  1. ファイル名のサフィックスに .ps1 を使用して (例: AddUsersToHold.ps1)、次のテキストを Windows PowerShell スクリプト ファイルに保存します。

    #script begin
    " " 
    write-host "***********************************************"
    write-host "   Office 365 Security & Compliance Center   " -foregroundColor yellow -backgroundcolor darkgreen
    write-host "   eDiscovery cases - Add users to a hold   " -foregroundColor yellow -backgroundcolor darkgreen 
    write-host "***********************************************"
    " " 
    # Get user credentials & Connect to Office 365 SCC, SPO
    
    $credentials = Get-Credential -Message "Specify your credentials to connect to the Office 365 Security & Compliance Center and SharePoint Online"
    $s = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri "https://ps.compliance.protection.outlook.com/powershell-liveid" -Credential $credentials -Authentication Basic -AllowRedirection -SessionOption (New-PSSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheck)
    $a = Import-PSSession $s -AllowClobber
    
        if (!$s)
        {
            Write-Error "Couldn't create PowerShell session."
            return;
        }
    
    # Load the SharePoint assemblies from the SharePoint Online Management Shell
    # To install, go to http://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: http://go.microsoft.com/fwlink/p/?LinkId=255251 and then re-run this script."
            return;
        }
    }
    
    if (!$spCreds)
    {
        $spCreds = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($credentials.UserName, $credentials.Password)
    }
    
    # Get the user's MySite domain name. We use this to create the admin URL and root URL for OneDrive for Business
    ""
    $mySiteDomain = Read-Host "Enter the name of your organization's MySite domain. For example, 'contoso' for 'https://contoso-my.sharepoint.com'"
    ""
    
    # 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 Site 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"
    
    # Add the path of the User Profile Service to the SPO admin URL, then create a new webservice proxy to access it
    $proxyaddr = "$AdminUrl/_vti_bin/UserProfileService.asmx?wsdl"
    $UserProfileService= New-WebServiceProxy -Uri $proxyaddr -UseDefaultCredential False
    $UserProfileService.Credentials = $credentials
    
    # Take care of auth cookies
    $strAuthCookie = $spCreds.GetAuthenticationCookie($AdminUrl)
    $uri = New-Object System.Uri($AdminUrl)
    $container = New-Object System.Net.CookieContainer
    $container.SetCookies($uri, $strAuthCookie)
    $UserProfileService.CookieContainer = $container
    $urls = @()
    foreach($emailAddress in $emailAddresses)
    {
          try{
            $prop = $UserProfileService.GetUserProfileByName("i:0#.f|membership|$emailAddress") | Where-Object { $_.Name -eq "PersonalSpace" }
            $url = $prop.values[0].value
    		if($url -ne $null){
            $furl = $mySiteUrlRoot + $url
            $urls += $furl
            Write-Host "- $emailAddress => $furl"
    		[array]$ODadded += $furl}
    	else{    
            Write-Warning "Couldn't locate OneDrive for $emailAddress"
    		[array]$ODExluded += $emailAddress
        }}
    	catch { 
    	Write-Warning "Could not locate OneDrive for $emailAddress"
    	[array]$ODExluded += $emailAddress
    	Continue }
    }
    
    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 $true | 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."}
    ""
    Write-host "Script complete!" -foregroundColor Yellow
    ""
    #script end
  2. ローカル コンピューターで Windows PowerShell を開き、スクリプトを保存したフォルダーに移動します。

  3. 以下のようなスクリプトを実行します。

    .\AddUsersToHold.ps1
  4. スクリプトで求められる情報を入力します。

    スクリプトは、リモート PowerShell を使ってセキュリティ/コンプライアンス センターに接続した後、電子情報開示ケースに新しい保留リストを作成して、リスト内のユーザーのメールボックスと OneDrive for Business サイトを追加します。セキュリティ/コンプライアンス センターの [電子情報開示] ページでケースに移動し、新しい保留リストを表示できます。

スクリプトは、実行を完了するときに、次のログ ファイルを作成して、スクリプトが存在するフォルダーに保存します。

  • LocationsOnHold.txt   スクリプトが正常に保留にしたメールボックスと OneDrive for Business サイトのリストが含まれます。

  • LocationsNotOnHold.txt   スクリプトが保留にしなかったメールボックスと OneDrive for Business サイトのリストが含まれます。メールボックスだけを持っていて、OneDrive for Business サイトを持たないユーザーは、保留にされなかった OneDrive for Business サイトのリストに含まれます。

  • GetCaseHoldPolicy.txt   スクリプトが新しく作成した保留リストに対して実行した Get-CaseHoldPolicy コマンドレットの出力が含まれます。このコマンドレットによって返される情報には、メールボックスと OneDrive for Business サイトが保留にされたユーザーのリストと、保留リストが有効か無効かが含まれます。

  • GetCaseHoldRule.txt   スクリプトが新しく作成した保留リストに対して実行した Get-CaseHoldRule コマンドレットの出力が含まれます。このコマンドレットによって返される情報には、スクリプトを使ってクエリに基づく保留リストを作成した場合に、検索クエリが含まれます。

先頭に戻る

スキルを磨く
トレーニングの探索
新機能を最初に入手
Office Insider に参加する

この情報は役に立ちましたか?

ご意見をいただきありがとうございます。

フィードバックをお寄せいただき、ありがとうございます。Office サポートの担当者におつなぎいたします。

×