Руководство. Использование REST API

Статья
08/23/2023

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

Если у вас нет подписки Azure, создайте бесплатную учетную запись перед началом работы.

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

Чтобы приступить к работе, необходимо иметь существующую учетную запись Microsoft Purview. Если у вас нет каталога, см. краткое руководство по созданию учетной записи Microsoft Purview.

Создание субъекта-службы (приложения)

Чтобы клиент REST API получить доступ к API плоскости данных Microsoft Purview, клиент должен иметь субъект-службу (приложение) и удостоверение, которое распознает Microsoft Purview и настроено на доверие. При выполнении вызовов REST API удостоверение субъекта-службы будет использоваться для авторизации.

Клиенты, которые использовали существующие субъекты-службы (идентификаторы приложений), имели высокий уровень сбоев. Поэтому рекомендуется создать субъект-службу для вызова API.

Чтобы создать субъект-службу, выполните приведенные далее действия.

Войдите на портал Azure.
На портале найдите и выберите Azure Active Directory.
На странице Azure Active Directory выберите Регистрация приложений в области слева.
Выберите Новая регистрация.
На странице Регистрация приложения выполните следующие действия.
1. Введите имя приложения (имя субъекта-службы).
2. Выберите Учетные записи только в этом каталоге организации (<только имя> клиента — Один клиент).
3. В поле URI перенаправления (необязательно) выберите Интернет и введите значение. Это значение не обязательно должно быть допустимой конечной точкой. https://exampleURI.com Сделать.
4. Нажмите Зарегистрировать.
На новой странице субъекта-службы скопируйте значения отображаемого имени и идентификатора приложения (клиента), чтобы сохранить их для дальнейшего использования.

Идентификатор приложения — это client_id значение в примере кода.

Чтобы использовать субъект-службу (приложение), необходимо знать пароль субъекта-службы, который можно найти с помощью:

На портал Azure найдите и выберите Azure Active Directory, а затем выберите Регистрация приложений в области слева.
Выберите субъект-службу (приложение) из списка.
Выберите Секреты сертификатов & в области слева.
Щелкните Создать секрет клиента.
На странице Добавление секрета клиента введите описание, выберите срок действия в разделе Срок действия и нажмите кнопку Добавить.

На странице Секреты клиента строка в столбце Значение нового секрета — это ваш пароль. Сохраните это значение.

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

После создания нового субъекта-службы необходимо назначить роли плоскости данных учетной записи purview субъекту-службе, созданному выше. Выполните следующие действия, чтобы назначить правильную роль для установления доверия между субъектом-службой и учетной записью Purview:

Перейдите на портал управления Microsoft Purview.
Выберите Карту данных в меню слева.
Выберите Коллекции.
Выберите корневую коллекцию в меню коллекции. Это будет верхняя коллекция в списке и будет иметь то же имя, что и ваша учетная запись Microsoft Purview.

Примечание.

Вы также можете назначить разрешение субъекта-службы любым вложенным коллекциям, а не корневой коллекции. Однако все API-интерфейсы будут ограничены этой коллекцией (и вложенными коллекциями, наследующими разрешения), и пользователи, пытающиеся вызвать API для другой коллекции, получат ошибки.
Перейдите на вкладку Назначения ролей .
Назначьте субъекту-службе, созданному ранее, следующие роли для доступа к различным плоскостям данных в Microsoft Purview. Подробные инструкции см. в статье Назначение ролей Azure с помощью портала управления Microsoft Purview.
- Роль куратора данных для доступа к плоскости данных каталога.
- Роль администратора источника данных для доступа к плоскости данных сканирования.
- Коллекция Администратор роль для доступа к плоскости данных учетной записи и политике метаданных Плоскость данных.
- Роль "Автор политики" для доступа к API политик DevOps
Примечание.

Только члены роли Администратор коллекции могут назначать роли плоскости данных в Microsoft Purview. Дополнительные сведения о ролях Microsoft Purview см. в разделе контроль доступа в Microsoft Purview.

Получение маркера

Вы можете отправить запрос POST по следующему URL-адресу, чтобы получить маркер доступа.

https://login.microsoftonline.com/{your-tenant-id}/oauth2/token

Идентификатор клиента можно найти, выполнив поиск по запросу Свойства клиента в портал Azure. Идентификатор будет доступен на странице свойств клиента.

В указанный выше URL-адрес необходимо передать следующие параметры:

client_id: идентификатор клиента приложения, зарегистрированного в Azure Active Directory и назначенного роли плоскости данных для учетной записи Microsoft Purview.
client_secret: секрет клиента, созданный для указанного выше приложения.
grant_type: это должно быть "client_credentials".
ресурс: 'https://purview.azure.net'

Ниже приведен пример запроса POST в PowerShell:

$tenantID = "12a345bc-67d1-ef89-abcd-efg12345abcde"

$url = "https://login.microsoftonline.com/$tenantID/oauth2/token"
$params = @{ client_id = "a1234bcd-5678-9012-abcd-abcd1234abcd"; client_secret = "abcd~a1234bcd56789012abcdabcd1234abcd"; grant_type = "client_credentials"; resource = ‘https://purview.azure.net’ }

Invoke-WebRequest $url -Method Post -Body $params -UseBasicParsing | ConvertFrom-Json

Пример маркера ответа:

    {
        "token_type": "Bearer",
        "expires_in": "86399",
        "ext_expires_in": "86399",
        "expires_on": "1621038348",
        "not_before": "1620951648",
        "resource": "https://purview.azure.net",
        "access_token": "<<access token>>"
    }

Совет

Если появляется сообщение об ошибке: Активация маркера между источниками разрешена только для типа клиента "Одностраничное приложение".

Проверьте заголовки запроса и убедитесь, что запрос не содержит заголовок origin.
Убедитесь, что для URI перенаправления задано значение Web в субъекте-службе.
Если вы используете такое приложение, как Postman, убедитесь, что ваше программное обеспечение обновлено.

Используйте указанный выше маркер доступа для вызова API плоскости данных.

Дальнейшие действия

Управление источниками данных REST API плоскости данных Microsoft Purview

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