使用 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 身分識別平臺 Entra ID 中註冊應用程式，才能呼叫 Microsoft Purview API 以進行電子檔探索。

應用程式可以透過兩種方式存取資料：

委派存取權：代表登入使用者執行動作的應用程式。
僅限應用程式存取權：以自己的身分識別運作的應用程式。

如需存取案例的詳細資訊，請參閱驗證和授權基本概念。

Microsoft Graph 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 範例。

電子檔探索案例清單的 PowerShell 範例。

如您所示，它會傳回租用戶內所有案例的清單。在深入研究案例時，記錄案例 ID 非常重要。您需要此 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

從下列輸出中可以看出，您需要從傳回的回應中擷取值。

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，以啟用匯出套件的程式設計下載，以及電子檔探索案例中匯出程式中的報表。

必要條件

執行本節中的設定步驟之前，請完成並驗證 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 ID>企業應用程式。
變更 [應用程式類型] 篩選器以顯示 [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 命令：
```
$spId = @{"AppId" = "b26e684c-5068-4120-a679-64a5d2c909d9" }
```
```
New-MgServicePrincipal -BodyParameter $spId;
```

注意事項

使用 PowerShell 腳本在 Microsoft Entra ID 中註冊新的應用程式，並指派應用程式驗證的 Microsoft Purview 電子文件探索 API 許可權（如果適用）。註冊應用程式之後，您必須設定用戶端密碼或憑證，並透過入口網站授與系統管理員同意。

步驟 2：將其他 MicrosoftPurviewEDiscovery 許可權指派給已註冊的應用程式

現在已新增服務主體，請更新先前在本文 Microsoft 圖形 API 一節中建立的應用程式許可權。登入 Azure 入口網站，然後移至 Microsoft Entra ID>應用程式註冊。

尋找並選取您在本文的 Microsoft 圖形 API 一節中建立的應用程式。
從導覽功能表中選取 API 許可權。
選取 [新增許可權]，然後選取 [我的組織使用的 API]。
搜尋 MicrosoftPurviewEDiscovery 並選取它。
選取 [應用程式許可權]。
選取 eDiscovery.Download.Read 的複選框。
選取 [新增許可權]。
在 [API 許可權] 上，選取 [授與管理員同意] (您的組織) ，以核准新增的許可權。

授與管理員同意後，組織新增許可權的狀態就會更新。

下載匯出套件和報告

擷取案例 ID 和匯出工作 ID

若要下載電子檔探索案例中匯出程式的匯出套件和報告，您需要案例標識碼和匯出作業的作業或作業標識碼。

若要使用 Microsoft Purview 入口網站來收集這項資訊：

開啟電子檔探索案例。
找出匯出程序。
選取 [複製支援資訊]。
將此資訊新增至文字編輯器 (，例如記事本) 。

或者，使用下列圖形 API 呼叫，以程式設計方式存取此資訊，以尋找您要匯出的案例識別碼和作業識別碼：

請遵循本文使用僅限應用程式存取連線到 Microsoft 圖形 API 一節中的步驟，連線到 Microsoft Graph。
如果您知道案例名稱，請搭配下列命令使用 eDocuments Graph PowerShell Cmdlet：
```
Get-MgSecurityCaseEdiscoveryCase | where {$_.displayname -eq "<Name of case>"} 
```
取得案例 ID 之後，請使用下列命令來查閱案例中的作業，以識別匯出的工作 ID：
```
Get-MgSecurityCaseEdiscoveryCaseOperation -EdiscoveryCaseId "<case ID>" 
```

匯出作業會記錄在 exportResult 動作下，以從搜尋直接匯出，或 ContentExport 動作以從檢閱集匯出。此 API 呼叫不會傳回匯出作業的名稱。若要尋找匯出程序的名稱，您必須查詢特定的作業ID。使用下列命令來尋找匯出程序的名稱：

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 呼叫不會傳回匯出作業的名稱。若要尋找匯出程序的名稱，您必須查詢特定的工作 ID。例如：

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

下載匯出套件

擷取匯出套件的下載 URL

exportFileMetaData 屬性包含下載匯出套件和報表所需的 URL。若要取得 URL，您需要執行匯出程式之電子檔探索案例的案例 識別碼 ，以及匯出程式的作業 識別碼 。

使用下列電子檔探索圖形 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。

下列範例指令碼可作為開發您自己的指令碼時參考，以啟用匯出套件的程式設計下載。

使用用戶端密碼連線

如果您將應用程式設定為使用用戶端密碼，請使用下列範例指令碼作為參考，以程式設計方式下載匯出套件和報告。將內容複製到記事本並將其另存為 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" }
    }
}

儲存腳本並開啟安裝下列 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' = "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" }
    }
}

當您儲存指令碼時，請開啟已安裝下列 PowerShell 模組的新 PowerShell 視窗：

Microsoft.Graph
MSAL.PS

瀏覽至您儲存指令碼的目錄，然後執行下列命令。

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

檢閱您指定為路徑的資料夾，以檢視下載的檔案。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-14

共用方式為

使用 Microsoft Purview API 進行電子檔探索

Microsoft Purview API

應用程式存取資料

Microsoft Graph API

必要條件

使用僅限應用程式存取連線到 Microsoft 圖形 API

透過用戶端密碼連線

透過憑證連線

叫用 Microsoft 圖形 API 呼叫

Microsoft Purview 電子文件探索 API

必要條件

設定步驟

步驟 1：在 Microsoft Entra ID 中註冊 MicrosoftPurviewEDiscovery 應用程式

步驟 2：將其他 MicrosoftPurviewEDiscovery 許可權指派給已註冊的應用程式

下載匯出套件和報告

擷取案例 ID 和匯出工作 ID

下載匯出套件

擷取匯出套件的下載 URL

下載匯出套件的範例指令碼

使用用戶端密碼連線

使用憑證連線

意見反應

其他資源