Использование API Microsoft Purview для обнаружения электронных данных

Интерфейс прикладного программирования Microsoft Purview (API) для обнаружения электронных данных в Microsoft Graph позволяет вашей организации автоматизировать повторяющиеся задачи и интегрироваться с существующими инструментами обнаружения электронных данных для создания повторяемых рабочих процессов, которые могут потребоваться отраслевым правилам. В этой статье содержатся рекомендации по настройке необходимых предварительных требований для предоставления доступа к API Microsoft Purview для обнаружения электронных данных. Это руководство основано на использовании доступа только для приложений к API с секретом клиента или самозаверяющего сертификата для проверки подлинности запросов.

API Microsoft Purview

API Microsoft Purview для обнаружения электронных данных включают два отдельных API:

Microsoft Graph: часть Microsoft.Graph.Security пространства имен и используется для работы с случаями обнаружения электронных данных.
API Microsoft Purview eDiscovery. Используется исключительно для программного скачивания пакетов, созданных при экспорте из наборов поиска и проверки в eDiscovery.

API обнаружения электронных данных в Microsoft Graph поддерживают только случаи обнаружения электронных данных с включенными функциями premium.

Список поддерживаемых вызовов API в вызовах Microsoft Graph см. в статье Использование API Microsoft Purview eDiscovery.

Доступ приложения к данным

Прежде чем выполнять какие-либо вызовы к API Microsoft Purview для обнаружения электронных данных, сначала необходимо зарегистрировать приложение на платформе удостоверений Майкрософт с идентификатором Entra.

Приложение может получить доступ к данным двумя способами:

Делегированный доступ. Приложение, действующее от имени пользователя, выполнившего вход.
Доступ только для приложений. Приложение, действующее с собственным удостоверением.

Дополнительные сведения о сценариях доступа см. в статье Основы проверки подлинности и авторизации.

API Microsoft Graph

Предварительные условия

Реализация доступа только для приложений включает регистрацию приложения в портал Azure, создание секрета или сертификатов клиента, назначение разрешений API, настройку субъекта-службы, а затем использование доступа только для приложений для вызова API Microsoft Graph. Чтобы зарегистрировать приложение, создать секрет или сертификаты клиента и назначить разрешения API, учетная запись должна быть администратором облачных приложений.

Дополнительные сведения о регистрации приложения в портал Azure см. в разделе Регистрация приложения с помощью платформа удостоверений Майкрософт.

Для предоставления согласия администратора на уровне клиента для Microsoft Purview eDiscovery приложений API требуется войти в систему от имени пользователя, которому разрешено предоставлять согласие от имени вашей организации. Дополнительные сведения см. в разделе Предоставление согласия администратора на уровне клиента приложению.

Для настройки субъекта-службы требуются следующие предварительные требования:

Компьютер с установленным модулем ExchangeOnlineManagement .
Учетная запись с ролью "Управление ролями", назначенной в Microsoft Purview.

Подробные инструкции по реализации доступа только для приложений для обнаружения электронных данных см. в статье Настройка доступа только для приложений для Microsoft Purview eDiscovery.

Подключение к Microsoft API Graph с помощью доступа только для приложений

Используйте командлет Connect-MgGraph в PowerShell для проверки подлинности и подключения к Microsoft Graph с помощью метода доступа только для приложений. Этот командлет позволяет приложению безопасно взаимодействовать с Microsoft Graph и позволяет просматривать API Microsoft Purview eDiscovery.

Подключение через секрет клиента

Чтобы подключиться с помощью секрета клиента, обновите и выполните следующий пример кода 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 Graph

После подключения можно начать вызовы к API Graph Майкрософт.

Например, можно перечислить случаи обнаружения электронных данных в клиенте с помощью API ediscoveryCases . В руководстве по каждой операции перечислены следующие сведения:

Разрешения, необходимые для вызова API
HTTP-запрос и метод
Сведения о заголовке и тексте запроса
Отклик
Примеры (HTTP, C#, CLI, Go, Java, PHP, PowerShell, Python)

Так как вы подключены через модуль Microsoft Graph PowerShell, можно использовать метод HTTP или PowerShell.

Сначала рассмотрим пример PowerShell .

Пример PowerShell для списка случаев обнаружения электронных данных.

Как видите, он возвращает список всех вариантов в клиенте. При более глубоком анализе дела важно записать идентификатор дела. Этот идентификатор потребуется для будущих вызовов API.

Теперь рассмотрим пример HTTP . Чтобы выполнить вызов с помощью PowerShell, используйте командлет Invoke-MgGraphRequest .

Сначала сохраните URL-адрес в переменной:

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

Затем выполните вызов API с помощью командлета Invoke-MgGraphRequest.

Invoke-MgGraphRequest -Method Get -Uri $uri

Как видно из следующих выходных данных, необходимо извлечь значения из возвращаемого ответа.

Пример PowerShell для выходных данных URL-адреса.

Элементы Value ответа можно сохранить в новой переменной с помощью следующей команды.

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

Пример PowerShell для извлечения URL-адреса.

Пример PowerShell для извлечения URL-адреса для случаев.

Эта команда возвращает коллекцию хэш-таблиц. При необходимости можно выполнить небольшой фрагмент кода PowerShell, чтобы преобразовать хэш-таблицы в объекты PowerShell, чтобы упростить использование с параметрами командлета, такими как format-table и format-list.

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

Пример PowerShell для преобразования хэш-таблиц.

API Microsoft Purview eDiscovery

Вы можете настроить API Microsoft Purview eDiscovery, чтобы включить программную загрузку пакетов экспорта и отчетов из процесса экспорта в случае обнаружения электронных данных.

Предварительные условия

Перед выполнением действий по настройке, описанных в этом разделе, выполните и проверьте конфигурацию, описанную в разделе Microsoft API Graph. Расширьте ранее зарегистрированное приложение в Microsoft Entra ID, включив необходимые разрешения для программной загрузки экспортного пакета.

Эта конфигурация уже обеспечивает следующие предварительные требования:

Зарегистрированные приложения в портал Azure настроены с соответствующим секретом клиента или сертификатом.
Субъекту-службе в Microsoft Purview назначены соответствующие роли обнаружения электронных данных.
Разрешения API обнаружения электронных данных Майкрософт, настроенные для Microsoft Graph.

Чтобы расширить разрешения API существующего зарегистрированного приложения, чтобы включить программную загрузку, выполните следующие действия.

Зарегистрируйте новое приложение Майкрософт и субъект-службу в клиенте.
Назначьте дополнительные разрешения API для ранее зарегистрированного приложения в портал Azure.

Чтобы предоставить согласие администратора на уровне клиента для разрешений приложений api Microsoft Purview eDiscovery, войдите от имени пользователя, которому разрешено предоставлять согласие от имени организации. Дополнительные сведения см. в разделе Предоставление согласия администратора на уровне клиента приложению.

Этапы конфигурации

Шаг 1. Регистрация приложения MicrosoftPurviewEDiscovery в Microsoft Entra ID

Выполните следующие действия:

Убедитесь, что приложение MicrosoftPurviewEDiscovery еще не зарегистрировано. Войдите в портал Azure и перейдите в раздел Microsoft Entra ID>Корпоративные приложения.
Измените фильтр "Тип приложения" , чтобы отобразить приложения Майкрософт.
В поле поиска введите MicrosoftPurviewEDiscovery. Должно отобразиться приложение MicrosoftPurviewEDiscovery . Если приложение MicrosoftPurviewEDiscovery отсутствует в списке, зарегистрируйте приложение в Microsoft Entra ID.

Чтобы зарегистрировать приложение, выполните следующие действия.
- Используйте модуль PowerShell Microsoft.Graph, чтобы зарегистрировать приложение MicrosoftPurviewEDiscovery в Microsoft Entra ID. Дополнительные сведения см. в статье Установка пакета SDK Для Microsoft Graph PowerShell.
- После установки модуля на компьютере выполните следующий командлет, чтобы подключиться к Microsoft Graph с помощью PowerShell:
```
Connect-MgGraph -scopes "Application.ReadWrite.All"
```
Если командлеты PowerShell Microsoft Graph используются впервые, может появиться запрос на согласие на необходимые разрешения.

Чтобы зарегистрировать приложение MicrosoftPurviewEDiscovery , выполните следующие команды PowerShell:
```
$spId = @{"AppId" = "00001111-aaaa-2222-bbbb-3333cccc4444" }
```
```
New-MgServicePrincipal -BodyParameter $spId;
```

Примечание.

Используйте сценарий PowerShell, чтобы зарегистрировать новое приложение в Microsoft Entra ID и назначить разрешения API Microsoft Purview eDiscovery для проверки подлинности приложения, если это применимо. После регистрации приложения необходимо настроить секрет клиента или сертификат и предоставить согласие администратора через портал.

Шаг 2. Назначение дополнительных разрешений MicrosoftPurviewEDiscovery зарегистрированным приложениям

Теперь, когда субъект-служба добавлен, обновите разрешения для ранее зарегистрированного приложения, созданного в разделе Microsoft API Graph этой статьи. Войдите в портал Azure и выберите Microsoft Entra ID>Регистрация приложений.

Найдите и выберите приложение, созданное в разделе Microsoft API Graph этой статьи.
Выберите Разрешения API в меню навигации.
Выберите Добавить разрешение , а затем — API, которые использует моя организация.
Найдите MicrosoftPurviewEDiscovery и выберите его.
Выберите Разрешения приложения.
Выберите поле проверка для eDiscovery.Download.Read.
Выберите Добавить разрешения.
В разделе Разрешения API выберите Предоставить согласие Администратор (ваша организация), чтобы утвердить добавленные разрешения.

После предоставления согласия администратора состояние добавленных разрешений обновляется для вашей организации.

Скачивание пакетов экспорта и отчетов

Получение идентификатора дела и идентификатора задания экспорта

Чтобы скачать пакеты экспорта и отчеты о процессе экспорта в случае обнаружения электронных данных, вам потребуется идентификатор дела и идентификатор операции или задания для задания экспорта.

Чтобы собрать эту информацию с помощью портала Microsoft Purview, выполните следующие действия:

Откройте дело обнаружения электронных данных.
Найдите процесс экспорта.
Выберите Копировать сведения о поддержке.
Добавьте эти сведения в текстовый редактор (например, Блокнот).

Кроме того, вы можете получить доступ к этой информации программным способом с помощью следующих вызовов API Graph, чтобы найти идентификатор дела и идентификатор задания, который требуется экспортировать:

Подключитесь к Microsoft Graph, выполнив действия, описанные в разделе Подключение к Microsoft API Graph с помощью доступа только для приложений этой статьи.
Если вы знаете имя случая, используйте командлеты PowerShell Graph для обнаружения электронных данных с помощью следующей команды:
```
Get-MgSecurityCaseEdiscoveryCase | where {$_.displayname -eq "<Name of case>"} 
```
Получив идентификатор обращения, найдите операции в случае, чтобы определить идентификатор задания для экспорта с помощью следующей команды:
```
Get-MgSecurityCaseEdiscoveryCaseOperation -EdiscoveryCaseId "<case ID>" 
```

Задания экспорта регистрируются под действием exportResult для прямого экспорта из поиска или ContentExport для экспорта из набора проверки. Имя заданий экспорта не возвращается этим вызовом API. Чтобы найти имя процесса экспорта, необходимо запросить идентификатор конкретной операции. Используйте следующую команду, чтобы найти имя процесса экспорта:

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

Имя операции экспорта включается в поле Дополнительные свойства .

Чтобы выполнить вызовы API HTTP непосредственно в списке случаев в вашей организации, см. статью List ediscoveryCases.

Чтобы напрямую выполнить вызовы API HTTP для перечисления операций для обращения, см. раздел Перечисление случаевПераций.

Используйте идентификатор варианта в вызове API, чтобы указать, из какого случая следует выводить список операций. Например, вы можете:

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

Имя заданий экспорта не возвращается при вызове API. Чтобы найти имя процесса экспорта, необходимо запросить конкретный идентификатор задания. Например, вы можете:

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

Скачивание пакета экспорта

Получение URL-адресов для скачивания для пакетов экспорта

Свойство exportFileMetaData содержит URL-адрес, необходимый для скачивания пакетов экспорта и отчетов. Чтобы получить URL-адрес, вам потребуется идентификатор дела обнаружения электронных данных, в котором выполняется процесс экспорта, и идентификатор операции для процесса экспорта.

Чтобы найти эти сведения, используйте следующие командлеты PowerShell Graph для обнаружения электронных данных:

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

$Operation.AdditionalProperties.exportFileMetadata

Чтобы напрямую выполнить вызовы API HTTP для возврата сведений exportFileMetaData для операции, см. раздел Перечисление caseOperations.

Каждый пакет экспорта на портале Microsoft Purview содержит запись в свойстве exportFileMetaData . В каждой записи перечислены следующие сведения:

Имя файла пакета экспорта
DownloadUrl для получения пакета экспорта
Размер экспортного пакета

Примеры скриптов для скачивания пакета экспорта

Так как API Microsoft Purview eDiscovery отделен от Microsoft API Graph, для авторизации запроса на скачивание требуется отдельный маркер проверки подлинности. Используйте модуль PowerShell MSAL.PS и командлет Get-MSALToken , чтобы получить отдельный маркер. Кроме того, необходимо подключиться к API Microsoft Graph с помощью командлета Connect-MgGraph .

Приведенные ниже примеры скриптов можно использовать в качестве справки при разработке собственных скриптов для включения программного скачивания пакетов экспорта.

Подключение с помощью секрета клиента

Если вы настроили приложение для использования секрета клиента, используйте следующий пример скрипта в качестве ссылки на скачивание пакета экспорта и отчетов программным способом. Скопируйте содержимое в Блокнот и сохраните его как 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" }
    }
}

Сохраните скрипт и откройте новое окно 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' = "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" }
    }
}

При сохранении скрипта откройте новое окно 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

Поделиться через

Использование API Microsoft Purview для обнаружения электронных данных

API Microsoft Purview

Доступ приложения к данным

API Microsoft Graph

Предварительные условия

Подключение к Microsoft API Graph с помощью доступа только для приложений

Подключение через секрет клиента

Подключение через сертификат

Вызов вызовов Microsoft API Graph

API Microsoft Purview eDiscovery

Предварительные условия

Этапы конфигурации

Шаг 1. Регистрация приложения MicrosoftPurviewEDiscovery в Microsoft Entra ID

Шаг 2. Назначение дополнительных разрешений MicrosoftPurviewEDiscovery зарегистрированным приложениям

Скачивание пакетов экспорта и отчетов

Получение идентификатора дела и идентификатора задания экспорта

Скачивание пакета экспорта

Получение URL-адресов для скачивания для пакетов экспорта

Примеры скриптов для скачивания пакета экспорта

Подключение с помощью секрета клиента

Подключение с помощью сертификата

Обратная связь

Дополнительные ресурсы