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 身分識別平台 Entra ID 中註冊應用程式,才能呼叫電子文件探索的 Microsoft Purview API。
應用程式可以透過兩種方式存取資料:
- 委派存取權: 代表已登入使用者行事的應用程式。
- 僅限應用程式存取: 以自己的身分識別執行的應用程式。
如需存取案例的詳細資訊,請參閱 驗證和授權基本概念。
重要事項
僅限應用程式驗證需要已啟用進階功能的電子文件探索案例。 委派驗證可用於 核心電子文件探索功能 ,包括案例、法律保留、搜尋和匯出。 無論驗證方法為何, (檢閱集、標記、分析) 進階版 API 作業都需要啟用進階功能。 如需訂閱需求的詳細資訊,請參閱電子 文件探索的訂閱需求。
Microsoft 圖形 API
Microsoft 圖形 API 的必要條件
實作僅限應用程式存取涉及在 Azure 入口網站中註冊應用程式、建立用戶端密碼/憑證、指派 API 權限、設定服務主體,然後使用僅限應用程式存取來呼叫 Microsoft Graph API。 若要註冊應用程式、建立用戶端密碼/憑證並指派 API 權限,該帳戶必須是 雲端應用程式系統管理員。
如需在 Azure 入口網站中註冊應用程式的詳細資訊,請參閱向 Microsoft 身分識別平台註冊應用程式。
針對 Microsoft Purview 電子文件探索 API 應用程式權限授予全租用戶系統管理員同意,您需要以已獲授權代表組織同意的使用者身分登入。 如需詳細資訊,請參閱將 全租用戶系統管理員同意授與應用程式。
設定服務主體需要下列必要條件:
- 安裝 了 ExchangeOnlineManagement 模組 的電腦。
- 在 Microsoft Purview 中具有指派角色管理角色的帳戶。
如需實作電子文件探索的僅限應用程式存取權的詳細步驟,請參閱 設定 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 範例。
如您所見,它會傳回租用戶內所有案例的清單。 當深入研究案例時,記錄案例 ID 非常重要。 您需要此識別碼才能進行未來的 API 呼叫。
現在,讓我們看看一個 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
從下列輸出可以看出,您必須從傳回的回應中擷取值。
您可以使用下列命令,將回應的 Value 元素儲存至新變數。
$cases = (Invoke-MgGraphRequest -Method Get -Uri $uri).value
此命令會傳回雜湊表格的集合。 您可以選擇性地執行少量 PowerShell 程式碼,將雜湊表格轉換成 PowerShell 物件,以便更輕鬆地與 Cmdlet 參數搭配使用 ,例如 format-table 和 format-list。
$CasesAsObjects = @()
foreach($i in $cases) {$CasesAsObjects += [pscustomobject]$i}
$CasesAsObjects | ft displayname,id,status
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 應用程式和服務主體。
- 將其他 API 權限指派給先前在 Azure 入口網站中註冊的應用程式。
若要針對 Microsoft Purview 電子文件探索 API 應用程式權限授與全租用戶系統管理員同意,請以已獲授權代表組織同意的使用者身分登入。 如需詳細資訊,請參閱將 全租用戶系統管理員同意授與應用程式。
設定步驟
步驟 1:在 Microsoft Entra ID 中註冊 MicrosoftPurviewEDiscovery 應用程式
完成下列步驟:
驗證 MicrosoftPurviewEDiscovery 應用程式是否尚未註冊。 登入 Azure 入口網站,然後移至 Microsoft Entra IDEnterprise>應用程式。
變更 [ 應用程式類型 ] 篩選以顯示 [Microsoft 應用程式]。
在搜尋方塊中,輸入 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 應用程式的應用程式識別碼,而不是應用程式 (用戶端) 您自己已註冊應用程式的識別碼。 在 範例下載指令碼的 export-token 領域中使用相同的 MicrosoftPurviewEDiscovery 應用程式識別碼。$spId = @{"AppId" = "<MicrosoftPurviewEDiscovery application ID>" }New-MgServicePrincipal -BodyParameter $spId;
注意事項
使用 PowerShell 指令碼在 Microsoft Entra ID 中註冊新的應用程式,並指派 Microsoft Purview 電子文件探索 API 權限以進行應用程式驗證。 註冊應用程式之後,您必須設定用戶端密碼或憑證,並透過入口網站授與系統管理員同意。
步驟 2:將其他 MicrosoftPurviewEDiscovery 權限指派給已註冊的應用程式
現在,服務主體已新增,請更新在本文的 Microsoft 圖形 API 一節中所建立先前註冊的應用程式的權限。 登入 Azure 入口網站,然後移至 Microsoft Entra IDApp>註冊。
- 尋找並選取您在本文 Microsoft 圖形 API 一節中建立的應用程式。
- 從導覽功能表中選取 API 權限 。
- 選取 [新增權限 ],然後 選取 [我的組織使用的 API]。
- 搜尋 MicrosoftPurviewEDiscovery 並選取它。
- 選取 應用程式權限。
- 選取 eDiscovery.Download.Read 的核取方塊。
- 選取 [新增權限]。
- 在 API 權限上,選取 [授與管理員同意] (貴組織) 核准新增的權限。
授與系統管理員同意之後,會針對貴組織更新新增權限的狀態。
下載匯出套件和報表
擷取案例識別碼和匯出工作識別碼
若要下載電子文件探索案例中匯出程序的匯出套件和報告,您需要案例識別碼以及匯出工作的作業或作業識別碼。
若要使用 Microsoft Purview 入口網站收集此資訊:
- 開啟電子文件探索案例。
- 找出匯出程序。
- 選取 複製支援資訊。
- 將此資訊新增至文字編輯器 (,例如記事本) 。
或者,使用下列 圖形 API 呼叫,以程式設計方式存取此資訊,以找出您想要匯出的案例識別碼和作業識別碼:
請依照本文使用僅限應用程式存取連結到 Microsoft 圖形 API 一節中的步驟連結到 Microsoft Graph。
如果您知道案例名稱,請使用 eDiscovery Graph PowerShell Cmdlet 與下列命令:
Get-MgSecurityCaseEdiscoveryCase | where {$_.displayname -eq "<Name of case>"}取得案例 ID 之後,請使用下列命令查詢案例中的作業,以識別匯出的作業 ID:
Get-MgSecurityCaseEdiscoveryCaseOperation -EdiscoveryCaseId "<case ID>"
如果是從搜尋直接匯出,匯出作業會記錄在 exportResult 動作下,或針對從檢閱集匯出的 ContentExport 。 此 API 呼叫不會傳回匯出作業的名稱。 若要尋找匯出程序的名稱,您必須查詢特定作業識別碼。 使用下列命令尋找匯出程序的名稱:
Get-MgSecurityCaseEdiscoveryCaseOperation -EdiscoveryCaseId "<case ID>" -CaseOperationId “<operation ID>”
匯出作業的名稱會包含在 AdditionalProperties 欄位中。
若要直接進行 HTTP API 呼叫以列出組織中的案例,請參閱 列出 ediscoveryCases。
若要直接進行 HTTP API 呼叫以列出案例的作業,請參閱 列出 caseOperations。
在 API 呼叫中使用案例 ID 來指示要從哪個案例列出作業。 例如:
https://graph.microsoft.com/v1.0/security/cases/ediscoveryCases/<CaseID>/operations/
此 API 呼叫不會傳回匯出作業的名稱。 若要尋找匯出程序的名稱,您必須查詢特定工作識別碼。 例如:
https://graph.microsoft.com/v1.0/security/cases/ediscoveryCases/<CaseID>/operations/<OperationID>
下載匯出套件
擷取匯出套件的下載 URL
exportFileMetaData 屬性包含下載匯出套件和報表所需的 URL。 若要取得 URL,您需要執行匯出程序的電子文件探索案例 的案例識別碼 ,以及匯出程序的作業 識別碼 。
使用下列 eDiscovery 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租用戶的識別碼。 |
appId |
應用程式 (用戶端) 您自己已註冊應用程式的識別碼,並使用 步驟 2 中的權限進行設定。 此值會針對 ClientId Microsoft Graph 和匯出權杖驗證傳遞給。 |
appSecret 或 certPath |
用戶端密碼值或您自己已註冊應用程式的憑證存放區路徑。 |
<MicrosoftPurviewEDiscovery application ID> |
在步驟 1 中註冊的 MicrosoftPurviewEDiscovery Microsoft 應用程式的應用程式識別碼。 在 Microsoft Entra IDEnterprise>應用程式>MicrosoftPurviewEDiscovery>概觀>應用程式識別碼中尋找此值。 請勿使用物件識別碼或您自己應用程式的應用程式 (用戶端) 識別碼。 |
在每個指令碼中,取代 <MicrosoftPurviewEDiscovery application ID> export-token 範圍並保留 /.default 尾碼。 此範圍會識別接收權杖的 Microsoft Purview 電子文件探索 API。 在憑證範例中, Scope 項目 $connectionDetails 會使用此值,同時 ClientId 仍會保留您自己已註冊的應用程式識別碼。
使用用戶端密碼連線
如果您將應用程式設定為使用用戶端密碼,請使用下列範例指令碼做為參考,以程式設計方式下載匯出套件和報告。 將內容複製到記事本並儲存為 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>”
檢閱您指定為路徑的資料夾,以檢視已下載的檔案。