Partager via

Utiliser les API Microsoft Purview pour eDiscovery

L’INTERFACE de programmation d’applications (API) Microsoft Purview pour eDiscovery dans Microsoft Graph permet à votre organization d’automatiser les tâches répétitives et de s’intégrer à vos outils eDiscovery existants pour créer des flux de travail reproductibles dont les réglementations du secteur peuvent avoir besoin. Cet article fournit des conseils sur la configuration des prérequis nécessaires pour permettre l’accès aux API Microsoft Purview pour eDiscovery. Ces conseils sont basés sur l’utilisation d’un accès d’application uniquement aux API, avec une clé secrète client ou un certificat auto-signé pour authentifier les demandes.

API Microsoft Purview

Les API Microsoft Purview pour eDiscovery incluent deux API distinctes :

  • Microsoft Graph : partie de l’espace Microsoft.Graph.Security de noms et utilisé pour travailler avec des cas eDiscovery.
  • API Microsoft Purview eDiscovery : utilisée exclusivement pour télécharger par programmation les packages créés lors de l’exportation à partir de recherches et de jeux de révision dans eDiscovery.

Les API eDiscovery dans Microsoft Graph prennent uniquement en charge les cas eDiscovery avec des fonctionnalités Premium activées.

Pour obtenir la liste des appels d’API pris en charge dans les appels Microsoft Graph, consultez Utiliser l’API Microsoft Purview eDiscovery.

Accès des applications aux données

Avant de pouvoir passer des appels aux API Microsoft Purview pour eDiscovery, vous devez d’abord inscrire une application dans la plateforme d’identités Microsoft, Entra ID.

Une application peut accéder aux données de deux manières :

  • Accès délégué : application agissant pour le compte d’un utilisateur connecté.
  • Accès à l’application uniquement : une application agissant avec sa propre identité.

Pour plus d’informations sur les scénarios d’accès, consultez Concepts de base de l’authentification et de l’autorisation.

API Microsoft Graph

Configuration requise

L’implémentation de l’accès d’application uniquement implique l’inscription d’une application dans Portail Azure, la création de secrets/certificats client, l’attribution d’autorisations d’API, la configuration d’un principal de service, puis l’utilisation d’un accès d’application uniquement pour appeler les API Microsoft Graph. Pour inscrire une application, créez une clé secrète client/des certificats et attribuez des autorisations d’API. Le compte doit être un administrateur d’application cloud.

Pour plus d’informations sur l’inscription d’une application dans le Portail Azure, consultez Inscrire une application avec le Plateforme d'identités Microsoft.

L’octroi d’un consentement administrateur à l’échelle du locataire pour les autorisations d’application d’API Microsoft Purview eDiscovery nécessite que vous vous connectiez en tant qu’utilisateur autorisé à donner votre consentement au nom de votre organization. Pour plus d’informations, consultez Accorder un consentement administrateur à l’échelle du locataire à une application.

La configuration d’un principal de service nécessite les prérequis suivants :

Pour obtenir des instructions détaillées sur l’implémentation de l’accès d’application uniquement pour eDiscovery, consultez Configurer l’accès aux applications uniquement pour Microsoft Purview eDiscovery.

Connexion à Microsoft API Graph à l’aide de l’accès aux applications uniquement

Utilisez l’applet de commande Connect-MgGraph dans PowerShell pour vous authentifier et vous connecter à Microsoft Graph à l’aide de la méthode d’accès par application uniquement. Cette applet de commande permet à votre application d’interagir avec Microsoft Graph en toute sécurité et vous permet d’explorer les API Microsoft Purview eDiscovery.

Connexion via une clé secrète client

Pour vous connecter à l’aide d’une clé secrète client, mettez à jour et exécutez l’exemple de code PowerShell suivant.

$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

Connexion via un certificat

Pour vous connecter à l’aide d’un certificat, mettez à jour et exécutez l’exemple de code PowerShell suivant.

$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

Appeler des appels microsoft API Graph

Une fois connecté, vous pouvez commencer à passer des appels au API Graph Microsoft.

Par exemple, vous pouvez répertorier les cas eDiscovery dans le locataire à l’aide de l’API ediscoveryCases . Les conseils pour chaque opération répertorient les informations suivantes :

  • Autorisations requises pour effectuer l’appel d’API
  • Requête et méthode HTTP
  • Informations sur l’en-tête et le corps de la demande
  • Réponse
  • Exemples (HTTP, C#, CLI, Go, Java, PHP, PowerShell, Python)

Étant donné que vous êtes connecté via le module Microsoft Graph PowerShell, vous pouvez utiliser la méthode HTTP ou PowerShell.

Tout d’abord, examinons l’exemple PowerShell .

Exemple PowerShell pour la liste des cas eDiscovery.

Comme vous pouvez le voir, il retourne une liste de tous les cas au sein du locataire. Lorsque vous approfondissez un cas, il est important d’enregistrer l’ID de cas. Vous avez besoin de cet ID pour les futurs appels d’API.

Examinons maintenant un exemple HTTP . Vous utilisez l’applet de commande Invoke-MgGraphRequest pour effectuer l’appel à l’aide de PowerShell.

Tout d’abord, stockez l’URL dans une variable :

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

Utilisez ensuite l’applet de commande Invoke-MgGraphRequest pour effectuer l’appel d’API.

Invoke-MgGraphRequest -Method Get -Uri $uri

Comme vous pouvez le voir dans la sortie suivante, vous devez extraire les valeurs de la réponse retournée.

Exemple PowerShell pour la sortie d’URL.

Vous pouvez enregistrer les éléments Value de la réponse dans une nouvelle variable à l’aide de la commande suivante.

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

Exemple PowerShell pour l’extraction d’URL.

Exemple PowerShell pour extraire l’URL des cas.

Cette commande retourne une collection de tables de hachage. Si vous le souhaitez, vous pouvez exécuter un petit peu de code PowerShell pour convertir les tables de hachage en objets PowerShell pour faciliter l’utilisation avec des paramètres d’applet de commande tels que format-table et format-list.

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

Exemple PowerShell pour convertir des tables de hachage.

API Microsoft Purview eDiscovery

Vous pouvez configurer l’API Microsoft Purview eDiscovery pour activer le téléchargement programmatique des packages d’exportation et des rapports d’un processus d’exportation dans un cas eDiscovery.

Configuration requise

Avant d’exécuter les étapes de configuration de cette section, effectuez et validez la configuration détaillée dans la section Microsoft API Graph. Étendez l’application précédemment inscrite dans Microsoft Entra ID pour inclure les autorisations requises pour effectuer le téléchargement par programmation du package d’exportation.

Cette configuration fournit déjà les prérequis suivants :

  • L’application inscrite dans Portail Azure configurée avec la clé secrète client ou le certificat approprié.
  • Le principal de service dans Microsoft Purview a attribué les rôles eDiscovery appropriés.
  • Autorisations de l’API Microsoft eDiscovery configurées pour Microsoft Graph.

Pour étendre les autorisations d’API de l’application inscrite existante afin d’activer le téléchargement par programmation, procédez comme suit :

  • Inscrivez une nouvelle application Microsoft et un nouveau principal de service dans le locataire.
  • Attribuez des autorisations d’API supplémentaires à l’application précédemment inscrite dans le Portail Azure.

Pour accorder le consentement administrateur à l’échelle du locataire pour les autorisations d’application d’API Microsoft Purview eDiscovery, connectez-vous en tant qu’utilisateur autorisé à donner son consentement au nom du organization. Pour plus d’informations, consultez Accorder un consentement administrateur à l’échelle du locataire à une application.

Étapes de configuration

Étape 1 : Inscrire l’application MicrosoftPurviewEDiscovery dans Microsoft Entra ID

Suivez les étapes ci-dessous :

  1. Vérifiez que l’application MicrosoftPurviewEDiscovery n’est pas déjà inscrite. Connectez-vous au Portail Azure et accédez à Microsoft Entra ID>Applications d’entreprise.

  2. Modifiez le filtre Type d’application pour afficher Les applications Microsoft.

  3. Dans la zone de recherche, entrez MicrosoftPurviewEDiscovery. L’application MicrosoftPurviewEDiscovery doit s’afficher. Si l’application MicrosoftPurviewEDiscovery n’est pas répertoriée, inscrivez-la dans Microsoft Entra ID.

    Pour inscrire l’application, procédez comme suit :

    • Utilisez le module PowerShell Microsoft.Graph pour inscrire l’application MicrosoftPurviewEDiscovery dans Microsoft Entra ID. Pour plus d’informations, consultez Installer le Kit de développement logiciel (SDK) Microsoft Graph PowerShell.
    • Une fois le module installé sur un ordinateur, exécutez l’applet de commande suivante pour vous connecter à Microsoft Graph à l’aide de PowerShell :
    Connect-MgGraph -scopes "Application.ReadWrite.All"

    Si c’est la première fois que vous utilisez les applets de commande Microsoft Graph PowerShell, vous pouvez être invité à donner votre consentement aux autorisations requises.

    Pour inscrire l’application MicrosoftPurviewEDiscovery , exécutez les commandes PowerShell suivantes :

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

    New-MgServicePrincipal -BodyParameter $spId;

Remarque

Utilisez le script PowerShell pour inscrire une nouvelle application dans Microsoft Entra ID et affecter les autorisations d’API Microsoft Purview eDiscovery pour l’authentification de l’application, le cas échéant. Après avoir inscrit l’application, vous devez configurer la clé secrète client ou le certificat et accorder le consentement administrateur via le portail.

Étape 2 : Attribuer des autorisations MicrosoftPurviewEDiscovery supplémentaires à l’application inscrite

Maintenant que le principal de service est ajouté, mettez à jour les autorisations sur votre application précédemment inscrite créée dans la section Microsoft API Graph de cet article. Connectez-vous au Portail Azure et accédez à Microsoft Entra ID>Inscriptions d’applications.

  1. Recherchez et sélectionnez l’application que vous avez créée dans la section Microsoft API Graph de cet article.
  2. Sélectionnez Autorisations d’API dans le menu de navigation.
  3. Sélectionnez Ajouter une autorisation, puis API que mon organization utilise.
  4. Recherchez MicrosoftPurviewEDiscovery et sélectionnez-la.
  5. Sélectionnez Autorisations d’application.
  6. Sélectionnez la zone case activée pour eDiscovery.Download.Read.
  7. Sélectionnez Ajouter des autorisations.
  8. Dans Autorisations d’API, sélectionnez Accorder Administration consentement (votre organization) pour approuver les autorisations ajoutées.

Une fois le consentement administrateur accordé, le status des autorisations ajoutées est mis à jour pour votre organization.

Téléchargement des packages et des rapports d’exportation

Récupération de l’ID de cas et de l’ID du travail d’exportation

Pour télécharger les packages d’exportation et les rapports d’un processus d’exportation dans un cas eDiscovery, vous avez besoin de l’ID de cas et de l’ID d’opération ou de travail pour le travail d’exportation.

Pour collecter ces informations à l’aide du portail Microsoft Purview :

  • Ouvrez un cas eDiscovery.
  • Recherchez le processus d’exportation.
  • Sélectionnez Copier les informations de support.
  • Ajoutez ces informations dans un éditeur de texte (comme le Bloc-notes).

Vous pouvez également accéder à ces informations par programme en utilisant les appels API Graph suivants pour localiser l’ID de cas et l’ID de travail que vous souhaitez exporter :

  1. Connectez-vous à Microsoft Graph en suivant les étapes décrites dans la section Connexion à Microsoft API Graph à l’aide de l’accès aux applications uniquement de cet article.

  2. Utilisez les applets de commande PowerShell eDiscovery Graph avec la commande suivante si vous connaissez le nom du cas :

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

  3. Une fois que vous avez l’ID de cas, recherchez les opérations dans le cas pour identifier l’ID de travail pour l’exportation à l’aide de la commande suivante :

    Get-MgSecurityCaseEdiscoveryCaseOperation -EdiscoveryCaseId "<case ID>"

Les travaux d’exportation sont enregistrés sous une action exportResult pour une exportation directe à partir de la recherche ou ContentExport pour une exportation à partir d’un jeu de révision. Le nom des travaux d’exportation n’est pas retourné par cet appel d’API. Pour trouver le nom du processus d’exportation, vous devez interroger l’ID d’opération spécifique. Utilisez la commande suivante pour rechercher le nom du processus d’exportation :

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

Le nom de l’opération d’exportation est inclus dans le champ AdditionalProperties .

Pour effectuer des appels d’API HTTP directement à la liste des cas dans votre organization, consultez List ediscoveryCases.

Pour effectuer des appels d’API HTTP directement afin de répertorier les opérations d’un cas, consultez List caseOperations.

Utilisez l’ID de cas dans l’appel d’API pour indiquer le cas à partir duquel répertorier les opérations. Par exemple :

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

Le nom des travaux d’exportation n’est pas retourné avec cet appel d’API. Pour trouver le nom du processus d’exportation, vous devez interroger l’ID de travail spécifique. Par exemple :

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

Téléchargement d’un package d’exportation

Récupération des URL de téléchargement pour les packages d’exportation

La propriété exportFileMetaData contient l’URL dont vous avez besoin pour télécharger les packages et rapports d’exportation. Pour obtenir l’URL, vous avez besoin de l’ID de cas du cas eDiscovery dans lequel vous avez exécuté le processus d’exportation et de l’ID d’opération pour le processus d’exportation.

Utilisez les applets de commande PowerShell eDiscovery Graph suivantes pour rechercher ces informations :

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

$Operation.AdditionalProperties.exportFileMetadata

Pour effectuer des appels d’API HTTP directement afin de retourner les informations exportFileMetaData pour une opération, consultez List caseOperations.

Chaque package d’exportation dans le portail Microsoft Purview a une entrée dans la propriété exportFileMetaData . Chaque entrée répertorie les informations suivantes :

  • Nom du fichier de package d’exportation
  • DownloadUrl pour récupérer le package d’exportation
  • Taille du package d’exportation

Exemples de scripts pour télécharger le package d’exportation

Étant donné que l’API Microsoft Purview eDiscovery est distincte de Microsoft API Graph, vous avez besoin d’un jeton d’authentification distinct pour autoriser une demande de téléchargement. Utilisez le module PowerShell MSAL.PS et l’applet de commande Get-MSALToken pour obtenir un jeton distinct. Vous devez également vous connecter aux API Microsoft Graph à l’aide de l’applet de commande Connect-MgGraph .

Les exemples de scripts suivants peuvent être utilisés comme référence lors du développement de vos propres scripts pour activer le téléchargement programmatique des packages d’exportation.

Connexion avec une clé secrète client

Si vous avez configuré votre application pour utiliser une clé secrète client, utilisez l’exemple de script suivant comme référence pour télécharger le package d’exportation et les rapports par programme. Copiez le contenu dans le Bloc-notes et enregistrez-le sous 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" }
    }
}

Enregistrez le script et ouvrez une nouvelle fenêtre PowerShell avec les modules PowerShell suivants installés :

  • Microsoft.Graph
  • MSAL.PS

Accédez au répertoire dans lequel vous avez enregistré le script et exécutez la commande suivante :

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

Passez en revue le dossier que vous avez spécifié comme chemin d’accès pour afficher les fichiers téléchargés.

Connexion avec un certificat

Si vous avez configuré votre application pour utiliser un certificat, utilisez l’exemple de script suivant comme référence pour télécharger le package d’exportation et les rapports par programme. Copiez le contenu dans un éditeur de texte et enregistrez-le sous 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" }
    }
}

Lorsque vous enregistrez le script, ouvrez une nouvelle fenêtre PowerShell avec les modules PowerShell suivants installés :

  • Microsoft.Graph
  • MSAL.PS

Accédez au répertoire dans lequel vous avez enregistré le script et exécutez la commande suivante.

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

Passez en revue le dossier que vous avez spécifié comme chemin d’accès pour afficher les fichiers téléchargés.

  • Last updated on