Uso de las API de Microsoft Purview para eDiscovery

La Interfaz de programación de aplicaciones (API) de Microsoft Purview para eDiscovery en Microsoft Graph permite a su organización automatizar tareas repetitivas e integrarse con las herramientas de exhibición de documentos electrónicos existentes para crear flujos de trabajo repetibles que las regulaciones del sector puedan requerir. En este artículo se proporcionan instrucciones sobre cómo configurar los requisitos previos necesarios para habilitar el acceso a las API de Microsoft Purview para eDiscovery. Esta guía se basa en el uso del acceso de solo aplicación a las API, con un secreto de cliente o un certificado autofirmado para autenticar las solicitudes.

API de Microsoft Purview

Las API de Microsoft Purview para eDiscovery incluyen dos API independientes:

• Microsoft Graph: parte del Microsoft.Graph.Security espacio de nombres y se usa para trabajar con casos de eDiscovery.
• API de Microsoft Purview eDiscovery: se usa exclusivamente para descargar mediante programación paquetes creados al exportar desde búsquedas y conjuntos de revisión en eDiscovery.

Las API de eDiscovery en Microsoft Graph solo admiten casos de exhibición de documentos electrónicos con características premium habilitadas.

Para obtener una lista de las llamadas API admitidas dentro de las llamadas de Microsoft Graph, consulte Uso de la API de Microsoft Purview eDiscovery.

Acceso de la aplicación a los datos

Para poder realizar llamadas a las API de Microsoft Purview para eDiscovery, primero debe registrar una aplicación en microsoft Identity Platform, Entra ID.

Una aplicación puede acceder a los datos de dos maneras:

• Acceso delegado: una aplicación que actúa en nombre de un usuario que ha iniciado sesión.
• Acceso solo a la aplicación: una aplicación que actúa con su propia identidad.

Para obtener más información sobre los escenarios de acceso, consulte Conceptos básicos de autenticación y autorización.

API de Microsoft Graph

Requisitos previos

Implementar el acceso solo a la aplicación implica registrar una aplicación en Azure Portal, crear certificados o secretos de cliente, asignar permisos de API, configurar una entidad de servicio y, a continuación, usar el acceso de solo aplicación para llamar a las API de Microsoft Graph. Para registrar una aplicación, cree certificados o secretos de cliente y asigne permisos de API, la cuenta debe ser administrador de aplicaciones en la nube.

Para obtener más información sobre cómo registrar una aplicación en el Azure Portal, consulte Registro de una aplicación con el Plataforma de identidad de Microsoft.

La concesión de consentimiento de administrador en todo el inquilino para Microsoft Purview eDiscovery permisos de aplicación de API requiere que inicie sesión como usuario autorizado para dar su consentimiento en nombre de su organización. Para obtener más información, consulte Concesión de consentimiento de administrador para todo el inquilino a una aplicación.

La configuración de una entidad de servicio requiere los siguientes requisitos previos:

• Una máquina con el módulo ExchangeOnlineManagement instalado.
• Una cuenta que tiene asignado el rol De administración de roles en Microsoft Purview.

Para obtener pasos detallados sobre cómo implementar el acceso solo a la aplicación para eDiscovery, consulte Configuración del acceso solo a aplicaciones para Microsoft Purview eDiscovery.

Conexión a Microsoft Graph API mediante el acceso solo a la aplicación

Use el cmdlet Connect-MgGraph en PowerShell para autenticarse y conectarse a Microsoft Graph mediante el método de acceso de solo aplicación. Este cmdlet permite que la aplicación interactúe con Microsoft Graph de forma segura y le permite explorar las API de Microsoft Purview eDiscovery.

Conexión a través del secreto de cliente

Para conectarse mediante un secreto de cliente, actualice y ejecute el código de PowerShell de ejemplo siguiente.

$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

Conexión a través de un certificado

Para conectarse mediante un certificado, actualice y ejecute el código de PowerShell de ejemplo siguiente.

$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 

Invocación de llamadas de Microsoft Graph API

Después de conectarse, puede empezar a realizar llamadas a microsoft Graph API.

Por ejemplo, puede enumerar los casos de eDiscovery dentro del inquilino mediante la API ediscoveryCases . En la guía de cada operación se muestra la siguiente información:

• Permisos necesarios para realizar la llamada a la API
• Solicitud HTTP y método
• Información del encabezado y el cuerpo de la solicitud
• Respuesta
• Ejemplos (HTTP, C#, CLI, Go, Java, PHP, PowerShell, Python)

Dado que está conectado a través del módulo de PowerShell de Microsoft Graph, puede usar el método HTTP o PowerShell.

En primer lugar, echemos un vistazo al ejemplo de PowerShell .

Como puede ver, devuelve una lista de todos los casos dentro del inquilino. Al profundizar en un caso, es importante registrar el identificador de caso. Necesita este identificador para futuras llamadas API.

Ahora, echemos un vistazo a un ejemplo HTTP . Use el cmdlet Invoke-MgGraphRequest para realizar la llamada mediante PowerShell.

En primer lugar, almacene la dirección URL en una variable:

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

A continuación, use el cmdlet Invoke-MgGraphRequest para realizar la llamada API.

Invoke-MgGraphRequest -Method Get -Uri $uri

Como puede ver en la salida siguiente, debe extraer los valores de la respuesta devuelta.

Puede guardar los elementos Value de la respuesta a una nueva variable mediante el siguiente comando.

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

Este comando devuelve una colección de tablas hash. Opcionalmente, puede ejecutar un pequeño fragmento de código de PowerShell para convertir las tablas hash en objetos de PowerShell para facilitar su uso con parámetros de cmdlet, como format-table y format-list.

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

API de Microsoft Purview eDiscovery

Puede configurar la API de Microsoft Purview eDiscovery para habilitar la descarga mediante programación de paquetes de exportación y los informes de un proceso de exportación en un caso de exhibición de documentos electrónicos.

Requisitos previos

Antes de ejecutar los pasos de configuración de esta sección, complete y valide la configuración detallada en la sección Microsoft Graph API. Amplíe la aplicación registrada anteriormente en Microsoft Entra identificador para incluir los permisos necesarios para lograr la descarga mediante programación del paquete de exportación.

Esta configuración ya proporciona los siguientes requisitos previos:

• La aplicación registrada en Azure Portal configurada con el certificado o secreto de cliente adecuado.
• La entidad de servicio de Microsoft Purview asignó los roles de exhibición de documentos electrónicos pertinentes.
• Permisos de la API de eDiscovery de Microsoft configurados para Microsoft Graph.

Para ampliar los permisos de API de la aplicación registrada existente para habilitar la descarga mediante programación, siga estos pasos:

• Registre una nueva aplicación de Microsoft y una entidad de servicio en el inquilino.
• Asigne permisos de API adicionales a la aplicación registrada anteriormente en el Azure Portal.

Para conceder el consentimiento del administrador de todo el inquilino para Microsoft Purview eDiscovery permisos de aplicación de API, inicie sesión como un usuario autorizado para dar su consentimiento en nombre de la organización. Para obtener más información, consulte Concesión de consentimiento de administrador para todo el inquilino a una aplicación.

Pasos de la configuración

Paso 1: Registro de la aplicación MicrosoftPurviewEDiscovery en Microsoft Entra id.

Complete los pasos siguientes:

1. Valide que la aplicación MicrosoftPurviewEDiscovery aún no está registrada. Inicie sesión en el Azure Portal y vaya a Microsoft Entra ID>Aplicaciones empresariales.

2. Cambie el filtro Tipo de aplicación para mostrar Aplicaciones de Microsoft.

3. En el cuadro de búsqueda, escriba MicrosoftPurviewEDiscovery. Se debe mostrar la aplicación MicrosoftPurviewEDiscovery . Si la aplicación MicrosoftPurviewEDiscovery no aparece en la lista, registre la aplicación en Microsoft Entra identificador.

   Para registrar la aplicación, siga estos pasos:

   • Use el módulo de PowerShell Microsoft.Graph para registrar la aplicación MicrosoftPurviewEDiscovery en Microsoft Entra identificador. Para obtener más información, consulte Instalación del SDK de PowerShell de Microsoft Graph.
   • Una vez instalado el módulo en una máquina, ejecute el siguiente cmdlet para conectarse a Microsoft Graph mediante PowerShell:

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

   Si es la primera vez que usa cmdlets de PowerShell de Microsoft Graph, es posible que se le pida que dé su consentimiento para los permisos necesarios.

   Para registrar la aplicación MicrosoftPurviewEDiscovery , ejecute los siguientes comandos de PowerShell:

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

   New-MgServicePrincipal -BodyParameter $spId;
   

Paso 2: Asignar permisos adicionales de MicrosoftPurviewEDiscovery a la aplicación registrada

Ahora que se agrega la entidad de servicio, actualice los permisos de la aplicación registrada anteriormente creada en la sección Microsoft Graph API de este artículo. Inicie sesión en el Azure Portal y vaya a registros deMicrosoft Entra aplicación de identificador>.

1. Busque y seleccione la aplicación que creó en la sección Microsoft Graph API de este artículo.
2. Seleccione Permisos de API en el menú de navegación.
3. Seleccione Agregar un permiso y, a continuación, API que usa mi organización.
4. Busque MicrosoftPurviewEDiscovery y selecciónelo.
5. Seleccione Permisos de aplicación.
6. Active la casilla eDiscovery.Download.Read.
7. Seleccione Agregar permisos.
8. En Permisos de API, seleccione Conceder Administración consentimiento (su organización) para aprobar los permisos agregados.

Una vez concedido el consentimiento del administrador, el estado de los permisos agregados se actualiza para su organización.

Descarga de paquetes e informes de exportación

Recuperar el identificador de caso y el identificador de trabajo de exportación

Para descargar los paquetes de exportación e informes de un proceso de exportación en un caso de exhibición de documentos electrónicos, necesita el identificador de caso y el identificador de operación o trabajo para el trabajo de exportación.

Para recopilar esta información mediante el portal de Microsoft Purview:

• Abra un caso de exhibición de documentos electrónicos.
• Busque el proceso de exportación.
• Seleccione Copiar información de soporte técnico.
• Agregue esta información a un editor de texto (como el Bloc de notas).

Como alternativa, acceda a esta información mediante programación mediante las siguientes llamadas Graph API para buscar el identificador de caso y el identificador de trabajo que desea exportar:

1. Conéctese a Microsoft Graph siguiendo los pasos de la sección Conexión a Microsoft Graph API mediante el acceso solo a la aplicación de este artículo.

2. Use los cmdlets de PowerShell de eDiscovery Graph con el siguiente comando si conoce el nombre del caso:

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

3. Una vez que tenga el identificador de caso, busque las operaciones en el caso para identificar el identificador de trabajo para la exportación mediante el siguiente comando:

   Get-MgSecurityCaseEdiscoveryCaseOperation -EdiscoveryCaseId "<case ID>" 
   

Los trabajos de exportación se registran en una acción de exportResult para una exportación directa desde la búsqueda o ContentExport para una exportación desde un conjunto de revisión. Esta llamada API no devuelve el nombre de los trabajos de exportación. Para buscar el nombre del proceso de exportación, debe consultar el identificador de operación específico. Use el siguiente comando para buscar el nombre del proceso de exportación:

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

El nombre de la operación de exportación se incluye en el campo AdditionalProperties .

Para realizar llamadas a la API HTTP directamente para enumerar los casos de su organización, consulte Enumerar ediscoveryCases.

Para realizar llamadas a la API HTTP directamente para enumerar las operaciones de un caso, consulte Enumerar caseOperations.

Use el identificador de caso en la llamada API para indicar desde qué caso se van a enumerar las operaciones. Por ejemplo:

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

El nombre de los trabajos de exportación no se devuelve con esta llamada API. Para encontrar el nombre del proceso de exportación, debe consultar el identificador de trabajo específico. Por ejemplo:

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

Descarga de un paquete de exportación

Recuperación de las direcciones URL de descarga para los paquetes de exportación

La propiedad exportFileMetaData contiene la dirección URL que necesita para descargar los paquetes e informes de exportación. Para obtener la dirección URL, necesita el identificador de caso del caso de exhibición de documentos electrónicos en el que ejecutó el proceso de exportación y el identificador de operación para el proceso de exportación.

Use los siguientes cmdlets de PowerShell de eDiscovery Graph para encontrar esta información:

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

$Operation.AdditionalProperties.exportFileMetadata

Para realizar llamadas a la API HTTP directamente para devolver la información exportFileMetaData de una operación, consulte Enumeración de caseOperations.

Cada paquete de exportación del portal de Microsoft Purview tiene una entrada en la propiedad exportFileMetaData . Cada entrada muestra la siguiente información:

• Nombre del archivo del paquete de exportación
• DownloadUrl para recuperar el paquete de exportación
• Tamaño del paquete de exportación

Scripts de ejemplo para descargar el paquete de exportación

Dado que la API de Microsoft Purview eDiscovery es independiente de Microsoft Graph API, necesita un token de autenticación independiente para autorizar una solicitud de descarga. Use el módulo de PowerShell MSAL.PS y el cmdlet Get-MSALToken para obtener un token independiente. También debe conectarse a las API de Microsoft Graph mediante el cmdlet Connect-MgGraph .

Los scripts de ejemplo siguientes se pueden usar como referencia al desarrollar sus propios scripts para habilitar la descarga mediante programación de los paquetes de exportación.

Conexión con un secreto de cliente

Si configuró la aplicación para usar un secreto de cliente, use el siguiente script de ejemplo como referencia para descargar el paquete de exportación y los informes mediante programación. Copie el contenido en el Bloc de notas y guárdelo como 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" }
    }
}

Guarde el script y abra una nueva ventana de PowerShell con los siguientes módulos de PowerShell instalados:

• Microsoft.Graph
• MSAL.PS

Vaya al directorio donde guardó el script y ejecute el siguiente comando:

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

Revise la carpeta que especificó como ruta de acceso para ver los archivos descargados.

Conexión con un certificado

Si configuró la aplicación para usar un certificado, use el siguiente script de ejemplo como referencia para descargar el paquete de exportación y los informes mediante programación. Copie el contenido en un editor de texto y guárdelo como 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" }
    }
} 

Al guardar el script, abra una nueva ventana de PowerShell con los siguientes módulos de PowerShell instalados:

• Microsoft.Graph
• MSAL.PS

Vaya al directorio donde guardó el script y ejecute el siguiente comando.

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

Revise la carpeta que especificó como ruta de acceso para ver los archivos descargados.