Usar APIs do Microsoft Purview para Descoberta Eletrônica

A API (Interface de Programação de Aplicativos) do Microsoft Purview para Descoberta Eletrônica no Microsoft Graph permite que sua organização automatize tarefas repetitivas e integre-se às ferramentas de Descoberta Eletrônica existentes para criar fluxos de trabalho repetíveis que os regulamentos do setor possam exigir. Este artigo fornece diretrizes sobre como configurar os pré-requisitos necessários para habilitar o acesso às APIs do Microsoft Purview para Descoberta Eletrônica. Essas diretrizes se baseiam no uso do acesso somente de aplicativo às APIs, com um segredo do cliente ou um certificado autoassinado para autenticar as solicitações.

Microsoft Purview APIs

As APIs do Microsoft Purview para Descoberta Eletrônica incluem duas APIs separadas:

• Microsoft Graph: parte do Microsoft.Graph.Security namespace e usado para trabalhar com casos de Descoberta Eletrônica.
• API Descoberta Eletrônica do Microsoft Purview: usada exclusivamente para baixar programaticamente pacotes criados ao exportar de conjuntos de pesquisa e revisão na Descoberta Eletrônica.

As APIs de Descoberta Eletrônica no Microsoft Graph dão suporte a casos de Descoberta Eletrônica com e sem recursos premium habilitados. A autenticação delegada dá suporte aos principais recursos de Descoberta Eletrônica , como casos, retenções, pesquisas e exportações. A autenticação somente de aplicativo está disponível para casos com recursos premium habilitados e dá suporte a operações avançadas, como conjuntos de revisão, marcação e análise.

Para obter uma lista de chamadas de API com suporte nas chamadas do Microsoft Graph, consulte Usar a API de Descoberta Eletrônica do Microsoft Purview.

Acesso do aplicativo aos dados

Antes de fazer qualquer chamada para as APIs do Microsoft Purview para Descoberta Eletrônica, você deve primeiro registrar um aplicativo na Plataforma de Identidade da Microsoft, o Entra ID.

Um aplicativo pode acessar dados de duas maneiras:

• Acesso delegado: um aplicativo agindo em nome de um usuário conectado.
• Acesso somente aplicativo: um aplicativo agindo com sua própria identidade.

Para obter mais informações sobre cenários de acesso, consulte Noções básicas de autenticação e autorização.

API do Microsoft Graph

Pré-requisitos para a API do Graph Microsoft

A implementação do acesso somente aplicativo envolve registrar um aplicativo no portal do Azure, criar segredo/certificados do cliente, atribuir permissões de API, configurar uma entidade de serviço e, em seguida, usar o acesso somente aplicativo para chamar APIs do Microsoft Graph. Para registrar um aplicativo, criar segredos/certificados do cliente e atribuir permissões de API, a conta deve ser um Administrador de Aplicativos de Nuvem.

Para obter mais informações sobre como registrar um aplicativo no portal do Azure, consulte Registrar um aplicativo na plataforma de identidade da Microsoft.

A concessão de consentimento de administrador em todo o locatário para permissões de aplicativo da API de Descoberta Eletrônica do Microsoft Purview exige que você entre como um usuário autorizado a consentir em nome de sua organização. Para obter mais informações, consulte Conceder consentimento de administrador em todo o locatário a um aplicativo.

A configuração de uma entidade de serviço requer os seguintes pré-requisitos:

• Um computador com o módulo ExchangeOnlineManagement instalado.
• Uma conta que tem a função Gerenciamento de Funçõesatribuída no Microsoft Purview.

Para obter etapas detalhadas sobre como implementar o acesso somente de aplicativo para Descoberta Eletrônica, consulte Configurar o acesso somente de aplicativo para a Descoberta Eletrônica do Microsoft Purview.

Conectando-se à API do Graph usando o acesso somente de aplicativo

Use o cmdlet Connect-MgGraph no PowerShell para autenticar e se conectar ao Microsoft Graph usando o método de acesso somente aplicativo. Esse cmdlet permite que seu aplicativo interaja com o Microsoft Graph com segurança e permite que você explore as APIs de Descoberta Eletrônica do Microsoft Purview.

Conectando-se via segredo do cliente

Para se conectar usando um segredo do cliente, atualize e execute o seguinte código do PowerShell de exemplo.

$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

Conectando-se via certificado

Para se conectar usando um certificado, atualize e execute o seguinte código do PowerShell de exemplo.

$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 chamadas da API do Graph

Depois de se conectar, você poderá começar a fazer chamadas para a API do Graph.

Por exemplo, você pode listar os casos de Descoberta Eletrônica no locatário usando a API ediscoveryCases . As diretrizes para cada operação listam as seguintes informações:

• Permissões necessárias para fazer a chamada à API
• Método e solicitação HTTP
• Informações do cabeçalho e do corpo da solicitação
• Resposta
• Exemplos (HTTP, C#, CLI, Go, Java, PHP, PowerShell, Python)

Como você está conectado por meio do módulo Microsoft Graph PowerShell, pode usar o método HTTP ou PowerShell.

Primeiro, vamos examinar o exemplo do PowerShell .

Como você pode ver, ele retorna uma lista de todos os casos dentro do locatário. Ao se aprofundar em um caso, é importante registrar a ID do caso. Você precisará dessa ID para futuras chamadas à API.

Agora, vamos ver um exemplo de HTTP . Use o cmdlet Invoke-MgGraphRequest para fazer a chamada usando o PowerShell.

Primeiro, armazene a URL em uma variável:

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

Em seguida, use o cmdlet Invoke-MgGraphRequest para fazer a chamada à API.

Invoke-MgGraphRequest -Method Get -Uri $uri

Como você pode ver na saída a seguir, você precisa extrair os valores da resposta retornada.

Você pode salvar os elementos Value da resposta em uma nova variável usando o comando a seguir.

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

Esse comando retorna uma coleção de tabelas de hash. Opcionalmente, você pode executar um pequeno código do PowerShell para converter as tabelas de hash em objetos do PowerShell para facilitar o uso com parâmetros de cmdlet, como format-table e format-list.

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

Descoberta Eletrônica do Microsoft Purview API

Você pode configurar a API de Descoberta Eletrônica do Microsoft Purview para habilitar o download programático de pacotes de exportação e os relatórios de um processo de exportação em um caso de Descoberta Eletrônica.

Pré-requisitos para a API de Descoberta Eletrônica do Microsoft Purview

Antes de executar as etapas de configuração desta seção, conclua e valide a configuração detalhada na seção API do Graph. Estenda o aplicativo registrado anteriormente no Microsoft Entra ID para incluir as permissões necessárias para obter o download programático do pacote de exportação.

Essa configuração já fornece os seguintes pré-requisitos:

• Aplicativo registrado no portal do Azure configurado com o segredo ou certificado de cliente apropriado.
• A entidade de serviço no Microsoft Purview atribuiu as funções relevantes de Descoberta Eletrônica.
• Permissões da API de Descoberta Eletrônica da Microsoft configuradas para o Microsoft Graph.

Para estender as permissões de API do aplicativo registrado existente para habilitar o download programático, conclua as seguintes etapas:

• Registre um novo aplicativo Microsoft e entidade de serviço no locatário.
• Atribua permissões de API adicionais ao aplicativo registrado anteriormente no portal do Azure.

Para conceder consentimento de administrador em todo o locatário para permissões de aplicativo de APIs de Descoberta Eletrônica do Microsoft Purview, entre como um usuário autorizado a consentir em nome da organização. Para obter mais informações, consulte Conceder consentimento de administrador em todo o locatário a um aplicativo.

Etapas de configuração

Etapa 1: Registrar o aplicativo MicrosoftPurviewEDiscovery no Microsoft Entra ID

Conclua as seguintes etapas:

1. Valide se o aplicativo MicrosoftPurviewEDiscovery ainda não está registrado. Entre no portal do Azure e acesse Aplicativos Empresariais do Microsoft Entra ID>.

2. Altere o filtro Tipo de aplicativo para mostrar Aplicativos da Microsoft.

3. Na caixa de pesquisa, insira MicrosoftPurviewEDiscovery. O aplicativo MicrosoftPurviewEDiscovery deve ser exibido. Se o aplicativo MicrosoftPurviewEDiscovery não estiver listado, registre-o no Microsoft Entra ID.

   Para registrar o aplicativo, conclua as seguintes etapas:

   • Use o Módulo Microsoft.Graph PowerShell para registrar o aplicativo MicrosoftPurviewEDiscovery no Microsoft Entra ID. Para obter mais informações, consulte Instalar o SDK do Microsoft Graph PowerShell.
   • Depois que o módulo for instalado em um computador, execute o seguinte cmdlet para se conectar ao Microsoft Graph usando o PowerShell:

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

   Se esta for a primeira vez que você usa cmdlets do Microsoft Graph PowerShell, você poderá ser solicitado a consentir com as permissões necessárias.

   Para registrar o aplicativo MicrosoftPurviewEDiscovery , execute os seguintes comandos do PowerShell:

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

   New-MgServicePrincipal -BodyParameter $spId;
   

Etapa 2: atribuir permissões MicrosoftPurviewEDiscovery adicionais ao aplicativo registrado

Agora que a entidade de serviço foi adicionada, atualize as permissões no aplicativo registrado anteriormente criado na seção API do Graph deste artigo. Entre no portal do Azure e acesse Registros de Aplicativos do Microsoft Entra ID>.

1. Encontre e selecione o aplicativo criado na seção deste artigo sobre a API do Graph.
2. Selecione Permissões de API no menu de navegação.
3. Selecione Adicionar uma permissão e, em seguida, APIs usadas pela minha organização.
4. Pesquise por MicrosoftPurviewEDiscovery e selecione-o.
5. Selecione Permissões do Aplicativo.
6. Marque a caixa de marca para eDiscovery.Download.Read.
7. Selecione Adicionar permissões.
8. Nas permissões de API, selecione Conceder Consentimento de Administração (sua organização) para aprovar as permissões adicionadas.

Depois que o consentimento do administrador é concedido, o status das permissões adicionadas é atualizado para sua organização.

Baixando os pacotes de exportação e relatórios

Recuperando a ID da ocorrência e a ID do trabalho de exportação

Para baixar os pacotes de exportação e relatórios de um processo de exportação em um caso de Descoberta Eletrônica, você precisa da ID do caso e da ID da operação ou do trabalho para o trabalho de exportação.

Para coletar essas informações usando o portal do Microsoft Purview:

• Abra um caso de Descoberta Eletrônica.
• Localize o processo de exportação.
• Selecione Copiar informações de suporte.
• Adicione essas informações a um editor de texto (como o Bloco de notas).

Como alternativa, acesse essas informações programaticamente usando as seguintes chamadas da API do Graph para localizar a ID da ocorrência e a ID do trabalho que você deseja exportar:

1. Conecte-se ao Microsoft Graph seguindo as etapas na seção Conectando-se à API do Graph usando somente o aplicativo deste artigo.

2. Use os cmdlets do PowerShell do Graph de Descoberta Eletrônica com o seguinte comando se você souber o nome da ocorrência:

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

3. Depois de ter a ID da ocorrência, pesquise as operações na ocorrência para identificar a ID do trabalho para a exportação usando o seguinte comando:

   Get-MgSecurityCaseEdiscoveryCaseOperation -EdiscoveryCaseId "<case ID>"
   

Os trabalhos de exportação são registrados em uma ação de exportResult para uma exportação direta da pesquisa ou ContentExport para uma exportação de um conjunto de revisão. O nome dos trabalhos de exportação não é retornado por essa chamada à API. Para localizar o nome do processo de exportação, você deve consultar a ID da operação específica. Use o comando a seguir para localizar o nome do processo de exportação:

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

O nome da operação de exportação é incluído no campo AdditionalProperties .

Para fazer as chamadas à API HTTP diretamente para listar casos em sua organização, consulte Listar casos de descobertas.

Para fazer as chamadas à API HTTP diretamente para listar as operações de um caso, consulte Listar caseOperations.

Use a ID do caso na chamada à API para indicar de qual caso listar as operações. Por exemplo:

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

O nome dos trabalhos de exportação não é retornado com esta chamada à API. Para localizar o nome do processo de exportação, você deve consultar a ID do trabalho específico. Por exemplo:

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

Baixar um pacote de exportação

Recuperando as URLs de download para pacotes de exportação

A propriedade exportFileMetaData contém a URL necessária para baixar os pacotes e relatórios de exportação. Para obter a URL, você precisa da ID do caso de Descoberta Eletrônica em que executou o processo de exportação e a ID da operação para o processo de exportação.

Use os seguintes cmdlets do PowerShell do Graph de Descoberta Eletrônica para encontrar essas informações:

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

$Operation.AdditionalProperties.exportFileMetadata

Para fazer as chamadas à API HTTP diretamente para retornar as informações exportFileMetaData de uma operação, consulte Listar caseOperations.

Cada pacote de exportação no portal do Microsoft Purview tem uma entrada na propriedade exportFileMetaData . Cada entrada lista as seguintes informações:

• O nome do arquivo do pacote de exportação
• O downloadUrl para recuperar o pacote de exportação
• O tamanho do pacote de exportação

Scripts de exemplo para baixar o pacote de exportação

Como a API de Descoberta Eletrônica do Microsoft Purview é separada da API do Graph Microsoft, você precisa de um token de autenticação separado para autorizar uma solicitação de download. Use o módulo MSAL.PS do PowerShell e o cmdlet Get-MSALToken para obter um token separado. Você também precisa se conectar às APIs do Microsoft Graph usando o cmdlet Connect-MgGraph .

Os scripts de exemplo a seguir podem ser usados como referência ao desenvolver seus próprios scripts para habilitar o download programático dos pacotes de exportação.

Conectando-se com um segredo do cliente

Se você configurou seu aplicativo para usar um segredo do cliente, use o script de exemplo a seguir como referência para baixar o pacote de exportação e os relatórios programaticamente. Copie o conteúdo no Bloco de Notas e salve-o 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 "00001111-aaaa-2222-bbbb-3333cccc4444/.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" }
    }
}

Salve o script e abra uma nova janela do PowerShell com os seguintes módulos do PowerShell instalados:

• Microsoft.Graph
• MSAL.PS

Navegue até o diretório onde você salvou o script e execute o seguinte comando:

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

Revise a pasta especificada como o caminho para visualizar os arquivos baixados.

Conectando-se com um certificado

Se você configurou seu aplicativo para usar um certificado, use o script de exemplo a seguir como referência para baixar o pacote de exportação e os relatórios programaticamente. Copie o conteúdo em um editor de texto e salve-o 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' = "00001111-aaaa-2222-bbbb-3333cccc4444/.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" }
    }
}

Ao salvar o script, abra uma nova janela do PowerShell com os seguintes módulos do PowerShell instalados:

• Microsoft.Graph
• MSAL.PS

Navegue até o diretório onde você salvou o script e execute o seguinte comando.

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

Revise a pasta especificada como o caminho para visualizar os arquivos baixados.