将 Microsoft Purview API 用于电子数据展示

Microsoft Graph 中用于电子数据展示的 Microsoft Purview 应用程序编程接口 (API) 使组织能够自动执行重复性任务,并与现有电子数据展示工具集成,以生成行业法规可能需要的可重复工作流。 本文提供有关如何配置所需的先决条件以启用对 Microsoft Purview API 的访问权限以进行电子数据展示的指导。 本指南基于使用对 API 的仅应用访问,以及客户端密码或自签名证书来对请求进行身份验证。

Microsoft Purview API

用于电子数据展示的 Microsoft Purview API 包括两个独立的 API:

  • Microsoft Graph:命名空间的一部分 Microsoft.Graph.Security ,用于处理 电子数据展示事例。
  • Microsoft Purview 电子数据展示 API:专门用于以编程方式下载从电子数据展示中的搜索和审阅集导出时创建的包。

Microsoft Graph 中的电子数据展示 API 支持 启用或未启用高级功能的电子数据展示事例。 委派的身份验证支持 核心电子数据展示功能 ,例如案例、保留、搜索和导出。 仅应用身份验证适用于启用了高级功能的情况,并支持审阅集、标记和分析等高级操作。

有关 Microsoft Graph 调用中支持的 API 调用的列表,请参阅使用 Microsoft Purview 电子数据展示 API。

应用程序对数据的访问

在对电子数据展示的 Microsoft Purview API 进行任何调用之前,必须先在 Microsoft 标识平台 Entra ID 中注册应用。

应用程序可以通过两种方式访问数据:

  • 委派的访问权限:代表登录用户执行操作的应用。
  • 仅限应用访问:以自己的标识运行的应用。

有关访问场景的详细信息,请参阅 身份验证和授权基础知识。

重要

仅应用身份验证需要启用了高级功能的电子数据展示事例。 委派的身份验证适用于 核心电子数据展示功能 ,包括事例、法定保留、搜索和导出。 高级 API 操作 (审阅集、标记、分析) 需要启用高级功能,无论身份验证方法如何。 有关订阅要求的详细信息,请参阅 电子数据展示的订阅要求。

Microsoft 图形 API

Microsoft 图形 API 的先决条件

实现仅限应用的访问权限包括在 Azure 门户中注册应用、创建客户端密码/证书、分配 API 权限、设置服务主体,然后使用仅限应用访问来调用 Microsoft Graph API。 要注册应用程序、创建客户端密码/证书并分配 API 权限,该帐户必须是 云应用程序管理员。

有关在 Azure 门户中注册应用的详细信息,请参阅向 Microsoft 标识平台注册应用程序。

若要向 Microsoft Purview 电子数据展示 API 应用程序权限授予租户范围的管理员同意,需要以授权代表组织同意的用户身份登录。 有关详细信息,请参阅 向应用程序授予租户范围的管理员同意。

设置服务主体需要满足以下先决条件:

有关实现电子数据展示的仅限应用访问的详细步骤,请参阅为 Microsoft Purview 电子数据展示设置仅限应用的访问。

使用仅限应用的访问连接到 Microsoft 图形 API

使用 PowerShell 中的 Connect-MgGraph cmdlet 进行身份验证,并使用仅限应用的访问方法连接到 Microsoft Graph。 此 cmdlet 使你的应用能够与 Microsoft Graph 安全地交互,并使你能够浏览 Microsoft Purview 电子数据展示 API。

通过客户端密码连接

若要使用客户端密码进行连接,请更新并运行以下示例 PowerShell 代码。

$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

通过证书连接

若要使用证书进行连接,请更新并运行以下示例 PowerShell 代码。

$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

调用 Microsoft 图形 API 调用

连接后,可以开始调用 Microsoft 图形 API。

例如,可以使用 ediscoveryCases API 列出租户中的电子数据展示事例。 每个操作的指南列出了以下信息:

  • 进行 API 调用所需的权限
  • HTTP 请求和方法
  • 请求标头和正文信息
  • 响应
  • 示例 (HTTP、C#、CLI、Go、Java、PHP、PowerShell、Python)

由于你是通过 Microsoft Graph PowerShell 模块连接的,因此可以使用 HTTP 或 PowerShell 方法。

首先,我们来看一下 PowerShell 示例。

电子数据展示事例列表的 PowerShell 示例。

如你所见,它返回租户内所有案例的列表。 深入研究案例时,请务必记录案例 ID。 将来的 API 调用需要此 ID。

现在,我们来看一个 HTTP 示例。 可使用 Invoke-MgGraphRequest cmdlet 通过 PowerShell 进行调用。

首先,将 URL 存储在一个变量中:

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

然后使用 Invoke-MgGraphRequest cmdlet 进行 API 调用。

Invoke-MgGraphRequest -Method Get -Uri $uri

从以下输出中可以看出,需要从返回的响应中提取值。

URL 输出的 PowerShell 示例。

可以使用以下命令将响应的 Value 元素保存到新变量。

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

用于提取 URL 的 PowerShell 示例。

用于提取事例 URL 的 PowerShell 示例。

此命令返回哈希表的集合。 (可选)可以运行少量 PowerShell 代码将哈希表转换为 PowerShell 对象,以便更轻松地与 cmdlet 参数(如 format-table 和 format-list)配合使用。

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

用于转换哈希表的 PowerShell 示例。

Microsoft Purview 电子数据展示 API

可以配置 Microsoft Purview 电子数据展示 API,以启用从电子数据展示事例中的导出过程中以编程方式下载导出包和报告。

重要

政府社区云 (GCC) 目前不支持通过 Microsoft Graph 对电子数据展示导出下载进行基于应用的身份验证。 此限制特定于导出下载,不是对电子数据展示 API 基于应用的身份验证的一般限制。

Microsoft Purview 电子数据展示 API 的先决条件

在本部分执行配置步骤之前,请完成并验证 Microsoft 图形 API 部分中详述的配置。 扩展之前在 Microsoft Entra ID 中注册的应用,以包含实现导出包的编程下载所需的权限。

此配置已提供以下先决条件:

  • 使用相应的客户端密码或证书配置在 Azure 门户中注册的应用。
  • Microsoft Purview 中的服务主体分配了相关的电子数据展示角色。
  • 为 Microsoft Graph 配置的 Microsoft 电子数据展示 API 权限。

若要扩展现有已注册应用的 API 权限以启用编程下载,请完成以下步骤:

  • 在租户中注册新的 Microsoft 应用程序和服务主体。
  • 向以前在 Azure 门户中注册的应用分配其他 API 权限。

若要向租户范围的管理员同意授予 Microsoft Purview 电子数据展示 API 应用程序权限,请以授权代表组织同意的用户身份登录。 有关详细信息,请参阅 向应用程序授予租户范围的管理员同意。

配置步骤

步骤 1:在 Microsoft Entra ID 中注册 MicrosoftPurviewEDiscovery 应用

完成以下步骤:

  1. 验证 MicrosoftPurviewEDiscovery 应用是否尚未注册。 登录到 Azure 门户并转到 Microsoft Entra IDEnterprise>应用程序。

  2. 更改 “应用程序类型 ”筛选器以显示 Microsoft 应用程序。

  3. 在搜索框中输入 MicrosoftPurviewEDiscovery。 应显示 MicrosoftPurviewEDiscovery 应用。 如果未列出 MicrosoftPurviewEDiscovery 应用,请在 Microsoft Entra ID 中注册该应用。

    要注册应用,请完成以下步骤:

    • 使用 Microsoft.Graph PowerShell 模块在 Microsoft Entra ID 中注册 MicrosoftPurviewEDiscovery 应用。 有关详细信息,请参阅 安装 Microsoft Graph PowerShell SDK。
    • 在计算机上安装模块后,运行以下 cmdlet 以使用 PowerShell 连接到 Microsoft Graph:
    Connect-MgGraph -scopes "Application.ReadWrite.All"
    

    如果这是第一次使用 Microsoft Graph PowerShell cmdlet,系统可能会提示你同意授予所需的权限。

    若要注册 MicrosoftPurviewEDiscovery 应用,请运行以下 PowerShell 命令。 替换 <MicrosoftPurviewEDiscovery application ID> 为 MicrosoftPurviewEDiscovery 应用的应用程序 ID,而不是你自己注册应用的应用程序 (客户端) ID。 在 示例下载脚本的导出令牌范围内使用此相同的 MicrosoftPurviewEDiscovery 应用程序 ID。

    $spId = @{"AppId" = "<MicrosoftPurviewEDiscovery application ID>" }
    
    New-MgServicePrincipal -BodyParameter $spId;
    

注意

使用 PowerShell 脚本在 Microsoft Entra ID 中注册新应用程序,并为应用程序身份验证分配 Microsoft Purview 电子数据展示 API 权限(如果适用)。 注册应用程序后,需要配置客户端密码或证书,并通过门户授予管理员同意。

步骤 2:向已注册的应用分配其他 MicrosoftPurviewEDiscovery 权限

添加服务主体后,请更新之前注册的应用的权限(在本文的 Microsoft 图形 API 部分中创建)。 登录到 Azure 门户,然后转到 Microsoft Entra ID>应用注册。

  1. 查找并选择在本文的 Microsoft 图形 API 部分中创建的应用。
  2. 从导航菜单中选择“ API 权限” 。
  3. 选择“ 添加权限 ”,然后选择 “我的组织使用的 API”。
  4. 搜索“MicrosoftPurviewEDiscovery 并选择它”。
  5. 选择应用程序权限。
  6. 选中电子数据展示.下载.读取的检查框。
  7. 选择 “添加权限”。
  8. 在“API 权限”上,选择“授予管理员同意” (组织) 以批准添加的权限。

授予管理员同意后,将更新组织所添加权限的状态。

下载导出包和报表

检索案例 ID 和导出作业 ID

若要下载电子数据展示事例中导出过程的导出程序包和报告,需要导出作业的案例 ID 和操作或作业 ID。

若要使用 Microsoft Purview 门户收集此信息,请执行以下操作:

  • 打开电子数据展示事例。
  • 找到导出进程。
  • 选择 “复制支持信息”。
  • 将此信息添加到文本编辑器 (如记事本) 。

或者,使用以下图形 API 调用以编程方式访问此信息,以查找要导出的案例 ID 和作业 ID:

  1. 按照本文使用仅限应用访问连接到 Microsoft 图形 API 部分中的步骤连接到 Microsoft Graph。

  2. 如果知道案例名称,请将 eDiscovery Graph PowerShell cmdlet 与以下命令配合使用:

    Get-MgSecurityCaseEdiscoveryCase | where {$_.displayname -eq "<Name of case>"}
    
  3. 获得案例 ID 后,使用以下命令查找案例中的操作,以确定导出的作业 ID:

    Get-MgSecurityCaseEdiscoveryCaseOperation -EdiscoveryCaseId "<case ID>"
    

对于从搜索直接导出,导出作业将在 exportResult 操作下记录,对于从审阅集导出的操作,则在 ContentExport 操作下记录。 此 API 调用不返回导出作业的名称。 要查找导出进程的名称,您必须查询特定的操作 ID。 使用以下命令查找导出进程的名称:

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

导出操作的名称包含在 AdditionalProperties 字段中。

若要直接进行 HTTP API 调用以列出组织中的案例,请参阅 列出电子数据展示案例。

若要直接进行 HTTP API 调用以列出案例的操作,请参阅 列出 caseOperations。

在 API 调用中使用案例 ID 指示要从哪个案例中列出操作。 例如:

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

此 API 调用不会返回导出作业的名称。 要查找导出进程的名称,您必须查询特定的作业 ID。 例如:

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

下载导出程序包

检索导出程序包的下载 URL

exportFileMetaData 属性包含下载导出包和报表所需的 URL。 若要获取 URL,需要运行导出过程的电子数据展示事例的案例 ID 和导出过程的操作 ID 。

使用以下电子数据展示 Graph PowerShell cmdlet 查找此信息:

$operation = Get-MgSecurityCaseEdiscoveryCaseOperation -EdiscoveryCaseId "<case ID>" -CaseOperationId “<operation ID>”
$Operation.AdditionalProperties.exportFileMetadata

若要直接进行 HTTP API 调用以返回操作的 exportFileMetaData 信息,请参阅 列出 caseOperations。

Microsoft Purview 门户中的每个导出包在 exportFileMetaData 属性中都有一个条目。 每个条目都列出了以下信息:

  • 导出包文件名
  • 用于检索导出包的 downloadUrl
  • 导出包的大小

用于下载导出包的示例脚本

由于 Microsoft Purview 电子数据展示 API 独立于 Microsoft 图形 API,因此需要单独的身份验证令牌来授权下载请求。 使用 MSAL.PS PowerShell 模块 和 Get-MSALToken cmdlet 获取单独的令牌。 还需要使用 Connect-MgGraph cmdlet 连接到 Microsoft Graph API。

在开发自己的脚本以启用导出包的编程下载时,以下示例脚本可用作参考。

在这两个脚本中对身份验证参数使用以下值:

参数或占位符 值
tenantId Microsoft Entra租户的目录 (租户) ID。
appId 应用程序 (客户端) 你自己注册应用的 ID,使用 步骤 2 中的权限进行了配置。 此值将传递给 ClientId Microsoft Graph 和导出令牌身份验证。
appSecret 或 certPath 客户端机密值或你自己注册的应用的证书存储路径。
<MicrosoftPurviewEDiscovery application ID> 在步骤 1 中注册的 MicrosoftPurviewEDiscovery Microsoft 应用程序的应用程序 ID。 在 Microsoft Entra IDEnterprise>应用程序>中查找此值MicrosoftPurviewEDiscovery>概述>应用程序 ID。 不要使用对象 ID 或你自己的应用的应用程序 (客户端) ID。

在每个脚本中,替换 <MicrosoftPurviewEDiscovery application ID> export-token 作用域并保留 /.default 后缀。 此范围标识接收令牌的 Microsoft Purview 电子数据展示 API。 在证书示例中, Scope 条 $connectionDetails 目使用此值,同时 ClientId 保留你自己注册应用的 ID。

使用客户端密码连接

如果将应用配置为使用客户端密码,请使用以下示例脚本作为参考以编程方式下载导出包和报表。 将内容复制到记事本中,另存为 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 "<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" }
    }
}

保存脚本并打开安装了以下 PowerShell 模块的新 PowerShell 窗口:

  • Microsoft.Graph
  • MSAL.PS

浏览到保存脚本的目录,并运行以下命令:

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

查看指定为路径的文件夹,以查看下载的文件。

使用证书连接

如果将应用配置为使用证书,请使用以下示例脚本作为参考以编程方式下载导出包和报表。 将内容复制到文本编辑器中,并将其另存为 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' = "<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" }
    }
}

保存脚本后,打开安装了以下 PowerShell 模块的新 PowerShell 窗口:

  • Microsoft.Graph
  • MSAL.PS

浏览到保存脚本的目录并运行以下命令。

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

查看指定为路径的文件夹,以查看下载的文件。