Utilizar as APIs do Microsoft Purview para Deteção de Dados Eletrónicos

A Interface de Programação de Aplicações (API) do Microsoft Purview para Deteção de Dados Eletrónicos no Microsoft Graph permite à sua organização automatizar tarefas repetitivas e integrar com as ferramentas de Deteção de Dados Eletrónicos existentes para criar fluxos de trabalho repetíveis que os regulamentos do setor possam exigir. Este artigo fornece orientações sobre como configurar os pré-requisitos necessários para permitir o acesso às APIs do Microsoft Purview para Deteção de Dados Eletrónicos. Esta orientação baseia-se na utilização do acesso apenas da aplicação às APIs, com um segredo do cliente ou um certificado autoassinado para autenticar os pedidos.

Microsoft Purview APIs

As APIs do Microsoft Purview para Deteção de Dados Eletrónicos incluem duas APIs separadas:

• Microsoft Graph: parte do Microsoft.Graph.Security espaço de nomes e utilizado para trabalhar com casos de Deteção de Dados Eletrónicos.
• Descoberta Eletrônica do Microsoft Purview API: utilizado exclusivamente para transferir pacotes criados através de programação ao exportar de pesquisas e conjuntos de revisão na Deteção de Dados Eletrónicos.

As APIs de Deteção de Dados Eletrónicos no Microsoft Graph só suportam casos de Deteção de Dados Eletrónicos com funcionalidades premium ativadas.

Para obter uma lista de chamadas à API suportadas nas chamadas do Microsoft Graph, veja Utilizar a API de Descoberta Eletrônica do Microsoft Purview.

Acesso da aplicação aos dados

Antes de poder fazer chamadas para as APIs do Microsoft Purview para Deteção de Dados Eletrónicos, primeiro tem de registar uma aplicação na Plataforma de Identidades da Microsoft, Entra ID.

Uma aplicação pode aceder aos dados de duas formas:

• Acesso delegado: uma aplicação a agir em nome de um utilizador com sessão iniciada.
• Acesso apenas à aplicação: uma aplicação a agir com a sua própria identidade.

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

API do Microsoft Graph

Pré-requisitos

A implementação do acesso apenas à aplicação envolve registar uma aplicação no portal do Azure, criar segredos/certificados de cliente, atribuir permissões de API, configurar um principal de serviço e, em seguida, utilizar o acesso apenas à aplicação para chamar as APIs do Microsoft Graph. Para registar uma aplicação, crie segredos/certificados de cliente e atribua permissões de API, a conta tem de ser um Administrador de Aplicações na Cloud.

Para obter mais informações sobre como registar uma aplicação no portal do Azure, veja Registar uma aplicação no plataforma de identidade da Microsoft.

A concessão do consentimento do administrador ao nível do inquilino para Descoberta Eletrônica do Microsoft Purview permissões de aplicação de API requer que inicie sessão como um utilizador autorizado a consentir em nome da sua organização. Para obter mais informações, veja Conceder consentimento do administrador ao nível do inquilino a uma aplicação.

A configuração de um principal de serviço requer os seguintes pré-requisitos:

• Um computador com o módulo ExchangeOnlineManagement instalado.
• Uma conta que tenha a função gestão de funções atribuída no Microsoft Purview.

Para obter os passos detalhados sobre como implementar o acesso apenas à aplicação para Deteção de Dados Eletrónicos, veja Configurar o acesso apenas à aplicação para Descoberta Eletrônica do Microsoft Purview.

Ligar ao Microsoft API do Graph através do acesso apenas à aplicação

Utilize o cmdlet Connect-MgGraph no PowerShell para autenticar e ligar ao Microsoft Graph através do método de acesso apenas à aplicação. Este cmdlet permite que a sua aplicação interaja com o Microsoft Graph de forma segura e permite-lhe explorar as APIs Descoberta Eletrônica do Microsoft Purview.

Ligar através do segredo do cliente

Para ligar através de 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

Ligar através de certificado

Para ligar através de 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 do Microsoft API do Graph

Depois de ligar, pode começar a fazer chamadas para o Microsoft API do Graph.

Por exemplo, pode listar os casos de Deteção de Dados Eletrónicos no inquilino com a API ediscoveryCases . A documentação de orientação para cada operação lista as seguintes informações:

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

Uma vez que está ligado através do módulo do PowerShell do Microsoft Graph, pode utilizar o método HTTP ou o PowerShell.

Primeiro, vamos ver o exemplo do PowerShell .

Como pode ver, devolve uma lista de todos os casos no inquilino. Ao aprofundar um caso, é importante registar o ID do caso. Precisa deste ID para futuras chamadas à API.

Agora, vamos ver um exemplo de HTTP . Utilize o cmdlet Invoke-MgGraphRequest para efetuar a chamada com o PowerShell.

Primeiro, armazene o URL numa variável:

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

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

Invoke-MgGraphRequest -Method Get -Uri $uri

Como pode ver na seguinte saída, tem de extrair os valores da resposta devolvida.

Pode guardar os elementos Value da resposta a uma nova variável com o seguinte comando.

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

Este comando devolve uma coleção de tabelas hash. Opcionalmente, pode executar um pequeno pouco de código do PowerShell para converter as tabelas hash em objetos do PowerShell para uma utilização mais fácil com parâmetros de cmdlets, como format-table e format-list.

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

API de Descoberta Eletrônica do Microsoft Purview

Pode configurar a API de Descoberta Eletrônica do Microsoft Purview para ativar a transferência programática de pacotes de exportação e os relatórios de um processo de exportação num caso de Deteção de Dados Eletrónicos.

Pré-requisitos

Antes de executar os passos de configuração nesta secção, conclua e valide a configuração detalhada na secção microsoft API do Graph. Expanda a aplicação registada anteriormente no Microsoft Entra ID para incluir as permissões necessárias para obter a transferência programática do pacote de exportação.

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

• A aplicação registada no portal do Azure configurada com o segredo ou certificado de cliente adequado.
• O principal de serviço no Microsoft Purview atribuiu as funções de Deteção de Dados Eletrónicos relevantes.
• Permissões da API de Deteção de Dados Eletrónicos da Microsoft configuradas para o Microsoft Graph.

Para expandir as permissões de API da aplicação registada existente para ativar a transferência programática, conclua os seguintes passos:

• Registe uma nova Aplicação Microsoft e um principal de serviço no inquilino.
• Atribua permissões de API adicionais à aplicação registada anteriormente no portal do Azure.

Para conceder o consentimento do administrador ao nível do inquilino para Descoberta Eletrônica do Microsoft Purview permissões de aplicação de APIs, inicie sessão como um utilizador autorizado a consentir em nome da organização. Para obter mais informações, veja Conceder consentimento do administrador ao nível do inquilino a uma aplicação.

Etapas de configuração

Passo 1: Registar a aplicação MicrosoftPurviewEDiscovery no Microsoft Entra ID

Conclua as seguintes etapas:

1. Confirme que a aplicação MicrosoftPurviewEDiscovery ainda não está registada. Inicie sessão no portal do Azure e aceda a Microsoft Entra ID>Aplicações Empresariais.

2. Altere o filtro Tipo de aplicação para mostrar As Aplicações Microsoft.

3. Na caixa de pesquisa, introduza MicrosoftPurviewEDiscovery. A aplicação MicrosoftPurviewEDiscovery deve ser apresentada. Se a aplicação MicrosoftPurviewEDiscovery não estiver listada, registe a aplicação no Microsoft Entra ID.

   Para registar a aplicação, conclua os seguintes passos:

   • Utilize o Módulo do PowerShell microsoft.Graph para registar a aplicação MicrosoftPurviewEDiscovery no ID Microsoft Entra. Para obter mais informações, veja Instalar o SDK do PowerShell do Microsoft Graph.
   • Assim que o módulo estiver instalado num computador, execute o seguinte cmdlet para ligar ao Microsoft Graph com o PowerShell:

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

   Se esta for a primeira vez que utiliza os cmdlets do PowerShell do Microsoft Graph, poderá ser-lhe pedido para consentir as permissões necessárias.

   Para registar a aplicação MicrosoftPurviewEDiscovery , execute os seguintes comandos do PowerShell:

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

   New-MgServicePrincipal -BodyParameter $spId;
   

Observação

Utilize o script do PowerShell para registar uma nova aplicação no Microsoft Entra ID e atribuir as permissões da API de Descoberta Eletrônica do Microsoft Purview para autenticação de aplicações, se aplicável. Depois de registar a aplicação, tem de configurar o segredo ou certificado do cliente e conceder o consentimento do administrador através do portal.

Passo 2: atribuir permissões adicionais do MicrosoftPurviewEDiscovery à aplicação registada

Agora que o principal de serviço foi adicionado, atualize as permissões na sua aplicação registada anteriormente criada na secção Microsoft API do Graph deste artigo. Inicie sessão no portal do Azure e aceda a Microsoft EntraRegistos de Aplicações de ID>.

1. Localize e selecione a aplicação que criou na secção Microsoft API do Graph deste artigo.
2. Selecione Permissões de API no menu de navegação.
3. Selecione Adicionar uma permissão e, em seguida, APIs que a minha organização utiliza.
4. Procure MicrosoftPurviewEDiscovery e selecione-a.
5. Selecione Permissões da Aplicação.
6. Selecione a caixa de marcar para Deteção de Dados Eletrónicos.Download.Read.
7. Selecione Adicionar Permissões.
8. Em Permissões de API, selecione Conceder consentimento Administração (a sua organização) para aprovar as permissões adicionadas.

Assim que o consentimento do administrador for concedido, a status das permissões adicionadas é atualizada para a sua organização.

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

Obter o ID do caso e o ID da tarefa de exportação

Para transferir os pacotes de exportação e os relatórios de um processo de exportação num caso de Deteção de Dados Eletrónicos, precisa do ID do caso e da operação ou ID da tarefa para a tarefa de exportação.

Para recolher estas informações através do portal do Microsoft Purview:

• Abra um caso de Deteção de Dados Eletrónicos.
• Localize o processo de exportação.
• Selecione Copiar informações de suporte.
• Adicione estas informações a um editor de texto (como o Bloco de Notas).

Em alternativa, aceda a estas informações programaticamente através das seguintes chamadas de API do Graph para localizar o ID do caso e o ID da tarefa que pretende exportar:

1. Ligue-se ao Microsoft Graph ao seguir os passos na secção Ligar à Microsoft API do Graph através do acesso apenas à aplicação deste artigo.

2. Utilize os cmdlets do PowerShell do Graph de Deteção de Dados Eletrónicos com o seguinte comando se souber o nome do caso:

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

3. Assim que tiver o ID do caso, procure as operações no caso para identificar o ID da tarefa para a exportação com o seguinte comando:

   Get-MgSecurityCaseEdiscoveryCaseOperation -EdiscoveryCaseId "<case ID>" 
   

As tarefas de exportação são registadas ao abrigo de uma ação exportResult para uma exportação direta da pesquisa ou ContentExport para uma exportação de um conjunto de revisão. O nome das tarefas de exportação não é devolvido por esta chamada à API. Para localizar o nome do processo de exportação, tem de consultar o ID de operação específico. Utilize o seguinte comando 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 está incluído no campo Propriedades Adicionais .

Para fazer as chamadas à API HTTP diretamente para listar casos na sua organização, veja Listar ediscoveryCases.

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

Utilize o ID do caso na chamada à API para indicar a que caso pretende listar as operações. Por exemplo:

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

O nome das tarefas de exportação não é devolvido com esta chamada à API. Para localizar o nome do processo de exportação, tem de consultar o ID de tarefa específico. Por exemplo:

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

Transferir um pacote de exportação

Obter os URLs de transferência para pacotes de exportação

A propriedade exportFileMetaData contém o URL de que precisa para transferir os pacotes e relatórios de exportação. Para obter o URL, precisa do ID do caso de Deteção de Dados Eletrónicos em que executou o processo de exportação e o ID da operação para o processo de exportação.

Utilize os seguintes cmdlets do PowerShell do Graph de Deteção de Dados Eletrónicos para encontrar estas informações:

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

$Operation.AdditionalProperties.exportFileMetadata

Para fazer as chamadas à API HTTP diretamente para devolver as informações exportFileMetaData de uma operação, veja List 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 ficheiro do pacote de exportação
• O downloadUrl para obter o pacote de exportação
• O tamanho do pacote de exportação

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

Uma vez que a API de Descoberta Eletrônica do Microsoft Purview está separada do Microsoft API do Graph, precisa de um token de autenticação separado para autorizar um pedido de transferência. Utilize o MSAL.PS Módulo do PowerShell e o cmdlet Get-MSALToken para obter um token separado. Também tem de se ligar às APIs do Microsoft Graph através do cmdlet Connect-MgGraph .

Os scripts de exemplo seguintes podem ser utilizados como referência ao desenvolver os seus próprios scripts para ativar a transferência programática dos pacotes de exportação.

Ligar a um segredo do cliente

Se tiver configurado a aplicação para utilizar um segredo do cliente, utilize o seguinte script de exemplo como referência para transferir o pacote de exportação e relatórios programaticamente. Copie o conteúdo para o Bloco de Notas e guarde-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 "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 o script e abra uma nova janela do PowerShell com os seguintes módulos do PowerShell instalados:

• Microsoft.Graph
• MSAL.PS

Navegue para o diretório onde guardou 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>”

Reveja a pasta que especificou como o caminho para ver os ficheiros transferidos.

Ligar com um certificado

Se tiver configurado a aplicação para utilizar um certificado, utilize o seguinte script de exemplo como referência para transferir o pacote de exportação e os relatórios através de programação. Copie o conteúdo para um editor de texto e guarde-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' = "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 guardar o script, abra uma nova janela do PowerShell com os seguintes módulos do PowerShell instalados:

• Microsoft.Graph
• MSAL.PS

Navegue para o diretório onde guardou 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>”

Reveja a pasta que especificou como o caminho para ver os ficheiros transferidos.