Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
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 eDiscovery 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 la 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.Securityespacio 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 a partir de búsquedas y revisar conjuntos en eDiscovery.
Las API de eDiscovery en Microsoft Graph admiten casos de eDiscovery con y sin características premium habilitadas. La autenticación delegada admite capacidades básicas de eDiscovery , como casos, retenciones, búsquedas y exportaciones. La autenticación de solo aplicación está disponible para los casos con características premium habilitadas y admite operaciones avanzadas como conjuntos de revisión, etiquetado y análisis.
Para obtener una lista de las llamadas API admitidas en 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, ID de Entra.
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 de aplicación: una aplicación que actúa con su propia identidad.
Para obtener más información acerca de los escenarios de acceso, consulte Conceptos básicos de autenticación y autorización.
Importante
La autenticación de solo aplicación requiere un caso de eDiscovery con características premium habilitadas. La autenticación delegada está disponible para las capacidades principales de eDiscovery , incluidos los casos, las retenciones legales, las búsquedas y las exportaciones. Las operaciones de API premium (conjuntos de revisión, etiquetado, análisis) requieren características premium habilitadas independientemente del método de autenticación. Para obtener más información sobre los requisitos de suscripción, consulte Requisitos de suscripción para eDiscovery.
API de Microsoft Graph
Requisitos previos para Microsoft Graph API
La implementación del acceso solo de aplicación implica registrar una aplicación en Azure Portal, crear secretos o certificados de cliente, asignar permisos de API, configurar una entidad de servicio y, después, usar el acceso solo de aplicación para llamar a las API de Microsoft Graph. Para registrar una aplicación, crear secretos o certificados de cliente y asignar permisos de API, la cuenta debe ser un administrador de aplicaciones en la nube.
Para obtener más información sobre el registro de una aplicación en Azure Portal, consulte Registro de una aplicación con la Plataforma de identidad de Microsoft.
Para conceder el consentimiento del administrador de todo el espacio empresarial para los permisos de aplicación de la API de Microsoft Purview eDiscovery, es necesario iniciar sesión como usuario autorizado para dar su consentimiento en nombre de la organización. Para obtener más información, consulte Conceder el consentimiento del administrador de todo el espacio empresarial a una aplicación.
La configuración de una entidad de servicio requiere de los siguientes requisitos previos:
- Una máquina con el módulo ExchangeOnlineManagement instalado.
- Una cuenta que tiene asignado el rol Administración de rolesen Microsoft Purview.
Para conocer los pasos detallados sobre cómo implementar el acceso solo de aplicación para eDiscovery, consulte Configurar el acceso solo de aplicación para Microsoft Purview eDiscovery.
Conectarse a la API de Microsoft Graph Graph API mediante el acceso solo de aplicación
Use el cmdlet Connect-MgGraph en PowerShell para autenticarse y conectarse a Microsoft Graph mediante el método de acceso sólo de 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.
Conectarse a través del secreto de cliente
Para conectarse mediante un secreto de cliente, actualice y ejecute el siguiente código de PowerShell de ejemplo.
$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
Conectarse mediante certificado
Para conectarse mediante un certificado, actualice y ejecute el siguiente código de PowerShell de ejemplo.
$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
Invocar llamadas de la API de Microsoft Graph API
Después de conectarse, puede empezar a realizar llamadas a la API de Microsoft Graph API.
Por ejemplo, puede enumerar los casos de eDiscovery dentro del inquilino mediante la API ediscoveryCases . Las instrucciones para cada operación enumeran la siguiente información:
- Permisos necesarios para realizar la llamada a la API
- Solicitud y método HTTP
- 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 la identificación del caso. Necesita este identificador para futuras llamadas API.
Ahora, veamos un ejemplo de HTTP . Use el cmdlet Invoke-MgGraphRequest para realizar la llamada mediante PowerShell.
En primer lugar, almacena la dirección URL en una variable:
$uri = "https://graph.microsoft.com/v1.0/security/cases/ediscoveryCases"
Después, use el cmdlet Invoke-MgGraphRequest para realizar la llamada API.
Invoke-MgGraphRequest -Method Get -Uri $uri
Como puede ver en el siguiente resultado, necesita extraer los valores de la respuesta devuelta.
Puede guardar los elementos de valor de la respuesta en 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 eDiscovery.
Importante
La autenticación basada en aplicaciones para descargas de exportación de eDiscovery a través de Microsoft Graph no se admite actualmente en Government Community Cloud (GCC). Esta limitación es específica para las descargas de exportación y no es una restricción general en la autenticación basada en aplicaciones para las API de eDiscovery.
Requisitos previos para la API de Microsoft Purview eDiscovery
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 ID 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:
- Aplicación registrada en Azure Portal configurada con el certificado o el secreto de cliente adecuado.
- La entidad de servicio en Microsoft Purview asignó los roles de eDiscovery relevantes.
- Permisos de la API de exhibición de documentos electrónicos 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 previamente en el Azure Portal.
Para conceder el consentimiento del administrador de todo el espacio empresarial para los permisos de aplicación de las API de Microsoft Purview eDiscovery, inicie sesión como un usuario autorizado para dar su consentimiento en nombre de la organización. Para obtener más información, consulte Conceder el consentimiento del administrador de todo el espacio empresarial a una aplicación.
Pasos de la configuración
Paso 1: registrar la aplicación MicrosoftPurviewEDiscovery en Microsoft Entra ID
Complete los pasos siguientes:
Valide que la aplicación MicrosoftPurviewEDiscovery no esté ya registrada. Inicie sesión en el Azure Portal y vaya a Aplicaciones de Microsoft Entra ID>Enterprise.
Cambie el filtro de tipo de aplicación para mostrar Aplicaciones de Microsoft.
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 ID.
Para registrar la aplicación, complete los pasos siguientes:
- Use el módulo Microsoft.Graph de PowerShell para registrar la aplicación MicrosoftPurviewEDiscovery en Microsoft Entra ID. Para obtener más información, consulte Instalación del SDK de PowerShell de Microsoft Graph.
- Después de instalar 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 acepte los permisos necesarios.
Para registrar la aplicación MicrosoftPurviewEDiscovery , ejecute los siguientes comandos de PowerShell. Reemplácelo
<MicrosoftPurviewEDiscovery application ID>con el id. de aplicación de la aplicación MicrosoftPurviewEDiscovery, no con el id. de aplicación (cliente) de su propia aplicación registrada. Use este mismo id. de aplicación MicrosoftPurviewEDiscovery en el ámbito de export-token en los scripts de descarga de ejemplo.$spId = @{"AppId" = "<MicrosoftPurviewEDiscovery application ID>" }New-MgServicePrincipal -BodyParameter $spId;
Nota:
Use el script de PowerShell para registrar una nueva aplicación en Microsoft Entra ID y asignar los permisos de API de Microsoft Purview eDiscovery para la autenticación de aplicaciones, si procede. Después de registrar la aplicación, debe configurar el secreto o certificado de cliente y otorgar el consentimiento del administrador a través del portal.
Paso 2: Asignar permisos adicionales de MicrosoftPurviewEDiscovery a la aplicación registrada
Ahora que se ha agregado 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 Azure Portal y vaya a Registros de aplicaciones de Microsoft Entra ID>.
- Busque y seleccione la aplicación que creó en la sección Microsoft Graph API de este artículo.
- Seleccione Permisos de API en el menú de navegación.
- Seleccione Agregar un permiso y las API que usa mi organización.
- Busque MicrosoftPurviewEDiscovery y selecciónelo.
- Seleccione Permisos de aplicación.
- Seleccione la casilla de verificación de eDiscovery.Download.Read.
- Seleccione Agregar permisos.
- En permisos de API, seleccione Conceder consentimiento del Administrador (su organización) para aprobar los permisos agregados.
Una vez otorgado el consentimiento del administrador, se actualiza el estado de los permisos agregados para su organización.
Descargar los paquetes e informes de exportación
Recuperación del identificador de caso y exportación del identificador de trabajo
Para descargar los paquetes e informes de exportación de un proceso de exportación en un caso de eDiscovery, 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 Microsoft Purview:
- Abra un caso de eDiscovery.
- Localice el proceso de exportación.
- Seleccione Copiar información de soporte técnico.
- Agregue esta información en un editor de texto (como el Bloc de notas).
Como alternativa, puede obtener acceso a esta información mediante programación mediante las siguientes llamadas de la Graph API para buscar el identificador de caso y el identificador de trabajo que desea exportar:
Conéctese a Microsoft Graph siguiendo los pasos de la sección Conectarse a Microsoft Graph API mediante el acceso solo de aplicación de este artículo.
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>"}Después de tener 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 bajo 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 a la API no devuelve el nombre de los trabajos de exportación. Para encontrar el nombre del proceso de exportación, debe consultar el identificador de operación específico. Utilice 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 las llamadas API HTTP directamente a los casos de lista de su organización, consulte Enumerar ediscoveryCases.
Para realizar las llamadas API HTTP directamente para enumerar las operaciones de un caso, consulte List caseOperations.
Use el identificador de caso en la llamada a la API para indicar desde qué caso 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/<OperationID>
Descargar un paquete de exportación
Recuperación de las 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 eDiscovery 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 las llamadas API HTTP directamente para devolver la información de exportFileMetaData para una operación, vea List caseOperations.
Cada paquete de exportación del portal Microsoft Purview tiene una entrada en la propiedad exportFileMetaData . En cada entrada se muestra la siguiente información:
- Nombre del archivo del paquete de exportación
- DownloadUrl para recuperar el paquete de exportación
- El 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 la API de Microsoft Graph API, necesita un token de autenticación independiente para autorizar una solicitud de descarga. Use el módulo MSAL.PS PowerShell 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 siguientes scripts de ejemplo se pueden usar como referencia al desarrollar sus propios scripts para habilitar la descarga mediante programación de los paquetes de exportación.
Use los siguientes valores para los parámetros de autenticación en ambos scripts:
| Parámetro o marcador de posición | Valor |
|---|---|
tenantId |
El identificador de directorio (inquilino) del inquilino de Microsoft Entra. |
appId |
El id. de aplicación (cliente) de su propia aplicación registrada, configurada con los permisos del Paso 2. Este valor se pasa para ClientId la autenticación de Microsoft Graph y export-token. |
appSecret o certPath |
El valor del secreto de cliente o la ruta de acceso del almacén de certificados de su propia aplicación registrada. |
<MicrosoftPurviewEDiscovery application ID> |
El id. de aplicación de la aplicación MicrosoftPurviewEDiscovery de Microsoft registrada en el paso 1. Busque este valor en las aplicaciones> de Microsoft Entra ID empresarial.> Informacióngeneral> sobreMicrosoftPurviewEDiscovery>Id. de aplicación. No uses el id. de objeto ni el id. de aplicación (cliente) de tu propia aplicación. |
En cada script, reemplácelo <MicrosoftPurviewEDiscovery application ID> en el ámbito export-token y conserve el /.default sufijo. Este ámbito identifica la API de Microsoft Purview eDiscovery que recibe el token. En el ejemplo del certificado, la Scope entrada usa $connectionDetails este valor, mientras sigue ClientId siendo el propio ID de la aplicación registrada.
Conectar con un secreto de cliente
Si ha configurado 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.ps1formato
[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 "<MicrosoftPurviewEDiscovery application ID>/.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 especificada como ruta de acceso para ver los archivos descargados.
Conectarse con un certificado
Si has configurado tu aplicación para usar un certificado, usa 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.ps1formato
[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' = "<MicrosoftPurviewEDiscovery application ID>/.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 especificada como ruta de acceso para ver los archivos descargados.