Usare le API Microsoft Purview per eDiscovery

L'API (Application Programming Interface) di Microsoft Purview per eDiscovery in Microsoft Graph consente all'organizzazione di automatizzare le attività ripetitive e di integrarsi con gli strumenti eDiscovery esistenti per creare flussi di lavoro ripetibili richiesti dalle normative del settore. Questo articolo fornisce indicazioni su come configurare i prerequisiti necessari per abilitare l'accesso alle API Microsoft Purview per eDiscovery. Queste indicazioni si basano sull'uso dell'accesso solo app alle API, con un segreto client o un certificato autofirmato per autenticare le richieste.

API Microsoft Purview

Le API Microsoft Purview per eDiscovery includono due API separate:

• Microsoft Graph: parte dello spazio dei nomi e usato per l'uso Microsoft.Graph.Security dei casi di eDiscovery.
• Microsoft Purview eDiscovery API: usata esclusivamente per scaricare a livello di codice i pacchetti creati durante l'esportazione da ricerche e set di revisione in eDiscovery.

Le API eDiscovery in Microsoft Graph supportano solo i casi di eDiscovery con funzionalità Premium abilitate.

Per un elenco delle chiamate API supportate all'interno delle chiamate di Microsoft Graph, vedere Usare l'API Microsoft Purview eDiscovery.

Accesso dell'applicazione ai dati

Prima di poter effettuare chiamate alle API Microsoft Purview per eDiscovery, è necessario registrare un'app in Microsoft Identity Platform, Entra ID.

Un'applicazione può accedere ai dati in due modi:

• Accesso delegato: app che agisce per conto di un utente connesso.
• Accesso solo app: un'app che agisce con la propria identità.

Per altre informazioni sugli scenari di accesso, vedere Nozioni di base sull'autenticazione e l'autorizzazione.

API di Microsoft Graph

Prerequisiti

L'implementazione dell'accesso solo app comporta la registrazione di un'app in portale di Azure, la creazione di certificati/segreti client, l'assegnazione di autorizzazioni API, la configurazione di un'entità servizio e quindi l'uso dell'accesso solo app per chiamare le API Microsoft Graph. Per registrare un'app, creare un segreto client/certificati e assegnare le autorizzazioni api l'account deve essere un amministratore di applicazioni cloud.

Per altre informazioni sulla registrazione di un'app nel portale di Azure, vedere Registrare un'applicazione con il Microsoft Identity Platform.

La concessione del consenso amministratore a livello di tenant per Microsoft Purview eDiscovery autorizzazioni dell'applicazione API richiede l'accesso come utente autorizzato a fornire il consenso per conto dell'organizzazione. Per altre informazioni, vedere Concedere il consenso amministratore a livello di tenant a un'applicazione.

La configurazione di un'entità servizio richiede i prerequisiti seguenti:

• Un computer con il modulo ExchangeOnlineManagement installato.
• Account con il ruolo Gestione ruoliassegnato in Microsoft Purview.

Per i passaggi dettagliati sull'implementazione dell'accesso solo app per eDiscovery, vedere Configurare l'accesso solo app per Microsoft Purview eDiscovery.

Connessione a Microsoft API Graph tramite l'accesso solo app

Usare il cmdlet Connect-MgGraph in PowerShell per autenticare e connettersi a Microsoft Graph usando il metodo di accesso solo app. Questo cmdlet consente all'app di interagire in modo sicuro con Microsoft Graph e consente di esplorare le API Microsoft Purview eDiscovery.

Connessione tramite segreto client

Per connettersi usando un segreto client, aggiornare ed eseguire il codice PowerShell di esempio seguente.

$clientSecret = "<client secret>" ## Update with client secret added to the registered app
$appID = "<APP ID>" ## Update with Application ID of registered/Enterprise app
$tenantId = "<Tenant ID>" ## Update with tenant ID
$ClientSecretPW = ConvertTo-SecureString "$clientSecret" -AsPlainText -Force
$clientSecretCred = New-Object System.Management.Automation.PSCredential -ArgumentList ("$appID", $clientSecretPW)
Connect-MgGraph -TenantId "$tenantId" -ClientSecretCredential $clientSecretCred

Connessione tramite certificato

Per connettersi usando un certificato, aggiornare ed eseguire il codice PowerShell di esempio seguente.

$certPath = "Cert:\currentuser\my\<xxxxxxxxxx>" ## Update with the cert thumbnail
$appID = "<APP ID>" ## Update with Application ID of registered/Enterprise app
$tenantId = "<Tenant ID>" ## Update with tenant ID
$ClientCert = Get-ChildItem $certPath 
Connect-MgGraph -TenantId $TenantId -ClientId $appId -Certificate $ClientCert 

Richiamare chiamate microsoft API Graph

Dopo la connessione, è possibile iniziare a effettuare chiamate a Microsoft API Graph.

Ad esempio, è possibile elencare i casi di eDiscovery all'interno del tenant usando l'API ediscoveryCases . Le indicazioni per ogni operazione elencano le informazioni seguenti:

• Autorizzazioni necessarie per effettuare la chiamata API
• Richiesta e metodo HTTP
• Informazioni sul corpo e sull'intestazione della richiesta
• Risposta
• Esempi (HTTP, C#, INTERFACCIA della riga di comando, Go, Java, PHP, PowerShell, Python)

Poiché si è connessi tramite il modulo PowerShell di Microsoft Graph, è possibile usare il metodo HTTP o PowerShell.

Per prima cosa, esaminiamo l'esempio di PowerShell .

Come si può vedere, restituisce un elenco di tutti i casi all'interno del tenant. Quando si approfondi un caso, è importante registrare l'ID del caso. Questo ID è necessario per le chiamate API future.

A questo punto, si esaminerà un esempio HTTP . Usare il cmdlet Invoke-MgGraphRequest per effettuare la chiamata usando PowerShell.

Prima di tutto, archiviare l'URL in una variabile:

$uri = "https://graph.microsoft.com/v1.0/security/cases/ediscoveryCases"

Usare quindi il cmdlet Invoke-MgGraphRequest per effettuare la chiamata API.

Invoke-MgGraphRequest -Method Get -Uri $uri

Come si può notare dall'output seguente, è necessario estrarre i valori dalla risposta restituita.

È possibile salvare gli elementi Value della risposta a una nuova variabile usando il comando seguente.

$cases = (Invoke-MgGraphRequest -Method Get -Uri $uri).value

Questo comando restituisce una raccolta di tabelle hash. Facoltativamente, è possibile eseguire un piccolo frammento di codice di PowerShell per convertire le tabelle hash in oggetti di PowerShell per facilitarne l'uso con parametri di cmdlet come format-table e format-list.

$CasesAsObjects = @()
foreach($i in $cases) {$CasesAsObjects += [pscustomobject]$i}
$CasesAsObjects | ft displayname,id,status

API Microsoft Purview eDiscovery

È possibile configurare l'API Microsoft Purview eDiscovery per abilitare il download a livello di codice dei pacchetti di esportazione e dei report da un processo di esportazione in un caso di eDiscovery.

Prerequisiti

Prima di eseguire i passaggi di configurazione in questa sezione, completare e convalidare la configurazione descritta in dettaglio nella sezione Microsoft API Graph. Estendere l'app registrata in precedenza nell'ID Microsoft Entra per includere le autorizzazioni necessarie per ottenere il download a livello di codice del pacchetto di esportazione.

Questa configurazione offre già i prerequisiti seguenti:

• L'app registrata in portale di Azure configurata con il segreto client o il certificato appropriato.
• All'entità servizio in Microsoft Purview sono stati assegnati i ruoli di eDiscovery pertinenti.
• Autorizzazioni dell'API Microsoft eDiscovery configurate per Microsoft Graph.

Per estendere le autorizzazioni API dell'app registrata esistente per abilitare il download a livello di codice, completare la procedura seguente:

• Registrare una nuova applicazione Microsoft e un'entità servizio nel tenant.
• Assegnare autorizzazioni API aggiuntive all'app registrata in precedenza nel portale di Azure.

Per concedere il consenso amministratore a livello di tenant per Microsoft Purview eDiscovery autorizzazioni dell'applicazione API, accedere come utente autorizzato a fornire il consenso per conto dell'organizzazione. Per altre informazioni, vedere Concedere il consenso amministratore a livello di tenant a un'applicazione.

Passaggi per la configurazione

Passaggio 1: Registrare l'app MicrosoftPurviewEDiscovery nell'ID Microsoft Entra

Completare i passaggi seguenti:

1. Verificare che l'app MicrosoftPurviewEDiscovery non sia già registrata. Accedere al portale di Azure e passare a Microsoft Entra ID>Applicazioni aziendali.

2. Modificare il filtro Tipo di applicazione per visualizzare Applicazioni Microsoft.

3. Nella casella di ricerca immettere MicrosoftPurviewEDiscovery. L'app MicrosoftPurviewEDiscovery deve essere visualizzata. Se l'app MicrosoftPurviewEDiscovery non è elencata, registrare l'app in Microsoft Entra ID.

   Per registrare l'app, completare la procedura seguente:

   • Usare il modulo PowerShell Microsoft.Graph per registrare l'app MicrosoftPurviewEDiscovery nell Microsoft Entra ID. Per altre informazioni, vedere Installare Microsoft Graph PowerShell SDK.
   • Dopo aver installato il modulo in un computer, eseguire il cmdlet seguente per connettersi a Microsoft Graph tramite PowerShell:

   Connect-MgGraph -scopes "Application.ReadWrite.All"
   

   Se questa è la prima volta che si usano i cmdlet di PowerShell di Microsoft Graph, potrebbe essere richiesto di fornire il consenso alle autorizzazioni necessarie.

   Per registrare l'app MicrosoftPurviewEDiscovery , eseguire i comandi di PowerShell seguenti:

   $spId = @{"AppId" = "b26e684c-5068-4120-a679-64a5d2c909d9" }
   

   New-MgServicePrincipal -BodyParameter $spId;
   

Passaggio 2: Assegnare autorizzazioni aggiuntive di MicrosoftPurviewEDiscovery all'app registrata

Ora che l'entità servizio è stata aggiunta, aggiornare le autorizzazioni per l'app registrata in precedenza creata nella sezione Microsoft API Graph di questo articolo. Accedere al portale di Azure e passare a registrazionidell'appcon ID> Microsoft Entra.

1. Trovare e selezionare l'app creata nella sezione Microsoft API Graph di questo articolo.
2. Selezionare Autorizzazioni API dal menu di spostamento.
3. Selezionare Aggiungi un'autorizzazione e quindi API usate dall'organizzazione.
4. Cercare MicrosoftPurviewEDiscovery e selezionarlo.
5. Selezionare Autorizzazioni applicazione.
6. Selezionare la casella di controllo per eDiscovery.Download.Read.
7. Selezionare Aggiungi autorizzazioni.
8. In Autorizzazioni API selezionare Concedi Amministrazione Consenso (l'organizzazione) per approvare le autorizzazioni aggiunte.

Dopo aver concesso il consenso amministratore, lo stato delle autorizzazioni aggiunte viene aggiornato per l'organizzazione.

Download dei pacchetti e dei report di esportazione

Recupero dell'ID caso ed ID processo di esportazione

Per scaricare i pacchetti di esportazione e i report di un processo di esportazione in un caso di eDiscovery, sono necessari l'ID del caso e l'ID dell'operazione o del processo per il processo di esportazione.

Per raccogliere queste informazioni tramite il portale di Microsoft Purview:

• Aprire un caso di eDiscovery.
• Individuare il processo di esportazione.
• Selezionare Copia informazioni di supporto.
• Aggiungere queste informazioni in un editor di testo ,ad esempio blocco note.

In alternativa, accedere a queste informazioni a livello di codice usando le chiamate di API Graph seguenti per individuare l'ID caso e l'ID processo da esportare:

1. Connettersi a Microsoft Graph seguendo i passaggi descritti nella sezione Connessione a Microsoft API Graph usando l'accesso solo app di questo articolo.

2. Usare i cmdlet di PowerShell di eDiscovery Graph con il comando seguente se si conosce il nome del caso:

   Get-MgSecurityCaseEdiscoveryCase | where {$_.displayname -eq "<Name of case>"} 
   

3. Dopo aver creato l'ID case, cercare le operazioni nel caso in cui identificare l'ID processo per l'esportazione usando il comando seguente:

   Get-MgSecurityCaseEdiscoveryCaseOperation -EdiscoveryCaseId "<case ID>" 
   

I processi di esportazione vengono registrati con un'azione exportResult per un'esportazione diretta dalla ricerca o ContentExport per un'esportazione da un set di revisione. Il nome dei processi di esportazione non viene restituito da questa chiamata API. Per trovare il nome del processo di esportazione, è necessario eseguire una query sull'ID operazione specifico. Usare il comando seguente per trovare il nome del processo di esportazione:

Get-MgSecurityCaseEdiscoveryCaseOperation -EdiscoveryCaseId "<case ID>" -CaseOperationId “<operation ID>”

Il nome dell'operazione di esportazione è incluso nel campo AdditionalProperties .

Per effettuare le chiamate API HTTP direttamente ai casi di elenco nell'organizzazione, vedere Elencare ediscoveryCases.

Per effettuare le chiamate API HTTP direttamente per elencare le operazioni per un caso, vedere Elencare caseOperations.

Usare l'ID case nella chiamata API per indicare da quale caso elencare le operazioni. Ad esempio:

https://graph.microsoft.com/v1.0/security/cases/ediscoveryCases/<CaseID>/operations/

Il nome dei processi di esportazione non viene restituito con questa chiamata API. Per trovare il nome del processo di esportazione, è necessario eseguire una query sull'ID processo specifico. Ad esempio:

https://graph.microsoft.com/v1.0/security/cases/ediscoveryCases/<CaseID>/operations/<Operation ID

Download di un pacchetto di esportazione

Recupero degli URL di download per i pacchetti di esportazione

La proprietà exportFileMetaData contiene l'URL necessario per scaricare i pacchetti e i report di esportazione. Per ottenere l'URL, è necessario l'ID caso del caso eDiscovery in cui è stato eseguito il processo di esportazione e l'ID operazione per il processo di esportazione.

Usare i cmdlet di PowerShell graph di eDiscovery seguenti per trovare queste informazioni:

$operation = Get-MgSecurityCaseEdiscoveryCaseOperation -EdiscoveryCaseId "<case ID>" -CaseOperationId “<operation ID>”

$Operation.AdditionalProperties.exportFileMetadata

Per effettuare direttamente chiamate all'API HTTP per restituire le informazioni exportFileMetaData per un'operazione, vedere Elencare caseOperations.

Ogni pacchetto di esportazione nel portale di Microsoft Purview include una voce nella proprietà exportFileMetaData . Ogni voce elenca le informazioni seguenti:

• Nome del file del pacchetto di esportazione
• DownloadUrl per recuperare il pacchetto di esportazione
• Dimensioni del pacchetto di esportazione

Script di esempio per scaricare il pacchetto di esportazione

Poiché l'API Microsoft Purview eDiscovery è separata da Microsoft API Graph, è necessario un token di autenticazione separato per autorizzare una richiesta di download. Usare il modulo MSAL.PS PowerShell e il cmdlet Get-MSALToken per ottenere un token separato. È anche necessario connettersi alle API di Microsoft Graph usando il cmdlet Connect-MgGraph .

Gli script di esempio seguenti possono essere usati come riferimento quando si sviluppano script personalizzati per abilitare il download a livello di codice dei pacchetti di esportazione.

Connessione con un segreto client

Se l'app è stata configurata per l'uso di un segreto client, usare lo script di esempio seguente come riferimento per scaricare il pacchetto di esportazione e i report a livello di codice. Copiare il contenuto nel Blocco note e salvarlo come DownloadExportUsingApp.ps1.

[CmdletBinding()]
param (
    [Parameter(Mandatory = $true)]
    [string]$tenantId,
    [Parameter(Mandatory = $true)]
    [string]$appId,
    [Parameter(Mandatory = $true)]
    [string]$appSecret,
    [Parameter(Mandatory = $true)]
    [string]$caseId,
    [Parameter(Mandatory = $true)]
    [string]$exportId,
    [Parameter(Mandatory = $true)]
    [string]$path = "D:\Temp",
    [ValidateSet($null, 'USGov', 'USGovDoD')]
    [string]$environment = $null    
)

if (-not(Get-Module -Name Microsoft.Graph -ListAvailable)) {
    Write-Host "Installing Microsoft.Graph module"
    Install-Module Microsoft.Graph -Scope CurrentUser
}

if (-not(Get-Module -Name MSAL.PS -ListAvailable)) {
    Write-Host "Installing MSAL.PS module"
    Install-Module MSAL.PS -Scope CurrentUser
}

$password = ConvertTo-SecureString $appSecret -AsPlainText -Force
$clientSecretCred = New-Object System.Management.Automation.PSCredential -ArgumentList ($appId, $password)

if (-not(Get-MgContext)) {
    Write-Host "Connect with credentials of a ediscovery admin (token for graph)"
    if (-not($environment)) {
        Connect-MgGraph -TenantId $TenantId -ClientSecretCredential $clientSecretCred
    }
    else {
        Connect-MgGraph -TenantId $TenantId -ClientSecretCredential $clientSecretCred -Environment $environment
    }
}

Write-Host "Connect with credentials of a ediscovery admin (token for export)"
$exportToken = Get-MsalToken -ClientId $appId -Scopes "b26e684c-5068-4120-a679-64a5d2c909d9/.default" -TenantId $tenantId -RedirectUri "http://localhost" -ClientSecret $password

$uri = "/v1.0/security/cases/ediscoveryCases/$($caseId)/operations/$($exportId)"

$export = Invoke-MgGraphRequest -Uri $uri;
if (-not($export)){
    Write-Host "Export not found"
    exit
}
else{
    $export.exportFileMetadata | % {
        Write-Host "Downloading $($_.fileName)"
        Invoke-WebRequest -Uri $_.downloadUrl -OutFile "$($path)\$($_.fileName)" -Headers @{"Authorization" = "Bearer $($exportToken.AccessToken)"; "X-AllowWithAADToken" = "true" }
    }
}

Salvare lo script e aprire una nuova finestra di PowerShell con i moduli di PowerShell seguenti installati:

• Microsoft.Graph
• MSAL.PS

Passare alla directory in cui è stato salvato lo script ed eseguire il comando seguente:

.\DownloadExportUsingApp.ps1 -tenantId “<tenant ID>” -appId “<App ID>” -appSecret “<Client Secret>” -caseId “<CaseID>” -exportId “<ExportID>” -path “<Output Path>”

Esaminare la cartella specificata come percorso per visualizzare i file scaricati.

Connessione con un certificato

Se l'app è stata configurata per l'uso di un certificato, usare lo script di esempio seguente come riferimento per scaricare il pacchetto di esportazione e i report a livello di codice. Copiare il contenuto in un editor di testo e salvarlo come DownloadExportUsingAppCert.ps1.

[CmdletBinding()]
param (
    [Parameter(Mandatory = $true)]
    [string]$tenantId,
    [Parameter(Mandatory = $true)]
    [string]$appId,
    [Parameter(Mandatory = $true)]
    [String]$certPath,
    [Parameter(Mandatory = $true)]
    [string]$caseId,
    [Parameter(Mandatory = $true)]
    [string]$exportId,
    [Parameter(Mandatory = $true)]
    [string]$path = "D:\Temp",
    [ValidateSet($null, 'USGov', 'USGovDoD')]
    [string]$environment = $null    
)

if (-not(Get-Module -Name Microsoft.Graph -ListAvailable)) {
    Write-Host "Installing Microsoft.Graph module"
    Install-Module Microsoft.Graph -Scope CurrentUser
}

if (-not(Get-Module -Name MSAL.PS -ListAvailable)) {
    Write-Host "Installing MSAL.PS module"
    Install-Module MSAL.PS -Scope CurrentUser
}

##$password = ConvertTo-SecureString $appSecret -AsPlainText -Force
##$clientSecretCred = New-Object System.Management.Automation.PSCredential -ArgumentList ($appId, $password)

$ClientCert = Get-ChildItem $certPath 

if (-not(Get-MgContext)) {
    Write-Host "Connect with credentials of a ediscovery admin (token for graph)"
    if (-not($environment)) {
        Connect-MgGraph -TenantId $TenantId -ClientId $appId -Certificate $ClientCert
    }
    else {
        Connect-MgGraph -TenantId $TenantId -ClientId $appId -Certificate $ClientCert -Environment $environment
    }
}

Write-Host "Connect with credentials of a ediscovery admin (token for export)"

$connectionDetails = @{
    'TenantId'          = $tenantId
    'ClientId'          = $appID
    'ClientCertificate' = $ClientCert
    'Scope' = "b26e684c-5068-4120-a679-64a5d2c909d9/.default"
}

$exportToken = Get-MsalToken @connectionDetails

$uri = "/v1.0/security/cases/ediscoveryCases/$($caseId)/operations/$($exportId)"

$export = Invoke-MgGraphRequest -Uri $uri;
if (-not($export)){
    Write-Host "Export not found"
    exit
}
else{
    $export.exportFileMetadata | % {
        Write-Host "Downloading $($_.fileName)"
        Invoke-WebRequest -Uri $_.downloadUrl -OutFile "$($path)\$($_.fileName)" -Headers @{"Authorization" = "Bearer $($exportToken.AccessToken)"; "X-AllowWithAADToken" = "true" }
    }
} 

Quando si salva lo script, aprire una nuova finestra di PowerShell con i moduli di PowerShell seguenti installati:

• Microsoft.Graph
• MSAL.PS

Passare alla directory in cui è stato salvato lo script ed eseguire il comando seguente.

.\DownloadExportUsingAppCert.ps1 -tenantId “<tenant ID>” -appId “<App ID>” -certPath “<Certificate Path>” -caseId “<CaseID>” -exportId “<ExportID>” -path “<Output Path>”

Esaminare la cartella specificata come percorso per visualizzare i file scaricati.