教程：对 API 进行身份验证

项目
11/13/2024

本教程介绍如何对 Microsoft Purview 数据平面 API 进行身份验证。任何想要将数据提交到 Microsoft Purview、将 Microsoft Purview 作为自动化过程的一部分，或者在 Microsoft Purview 上构建自己的用户体验的人都可以使用 API 执行此操作。

先决条件

若要开始，必须具有现有的 Microsoft Purview 帐户。如果没有目录，请参阅创建 Microsoft Purview 帐户的快速入门。

(应用程序) 创建服务主体

要使 API 客户端访问 Microsoft Purview 数据平面 API，客户端必须具有服务主体 (应用程序) ，以及Microsoft Purview 识别并配置为信任的标识。进行 API 调用时，该服务主体的标识将用于授权。

使用现有服务主体 (应用程序 ID) 的客户故障率很高。因此，建议创建新的服务主体来调用 API。

若要创建新的服务主体，请执行以下操作：

登录 Azure 门户。
在门户中，搜索并选择“Microsoft Entra ID”。
在“Microsoft Entra ID”页中，从左窗格中选择“应用注册”。
选择“新注册”。
在 “注册应用程序” 页上：
1. 输入应用程序 的名称 ， (服务主体名称) 。
2. 对于 “谁可以使用此应用程序或访问此 API？”，请选择希望使用此 API 的用户帐户类型。
  
  提示
  
  如果希望当前Microsoft Entra ID租户中的用户只能使用 REST API，请选择“此组织目录中的帐户仅 (<租户名称> - 单租户) 。否则，请考虑其他选项。
3. 对于 “重定向 URI (可选) ”，选择“ Web ”并输入值。此值不需要是有效的终结点。 https://exampleURI.com 会的。
4. 选择“注册”。
在新的服务主体页上，复制 “显示名称 ”和 “应用程序 (客户端) ID ”的值，以供以后保存。

应用程序 ID 是 client_id 示例代码中的值。

若要使用服务主体 (应用程序) ，需要知道服务主体的密码，可通过以下方式找到：

在Azure 门户中，搜索并选择“Microsoft Entra ID”，然后从左窗格中选择“应用注册”。
从列表中选择服务主体 (应用程序) 。
从左窗格中选择 “证书 & 机密 ”。
选择“新建客户端密码”。
在 “添加客户端密码 ”页上，输入 “说明”，在“ 过期”下选择过期时间，然后选择“ 添加”。

在 “客户端机密 ”页上，新机密的“ 值 ”列中的字符串是密码。保存此值。

使用服务主体设置身份验证

创建新的服务主体后，需要将 purview 帐户的数据平面角色分配给上面创建的服务主体。按照以下步骤分配正确的角色，以在服务主体和 Purview 帐户之间建立信任：

导航到 Microsoft Purview 治理门户。
在左侧菜单中选择“数据映射”。
选择“集合”。
在集合菜单中选择根集合。该集合将是列表中的顶级集合，其名称与 Microsoft Purview 帐户的名称相同。

注意

还可以将服务主体权限分配给任何子集合，而不是根集合。但是，所有 API 的作用域将限定为继承权限) 的集合 (和子集合，并且尝试为另一个集合调用 API 的用户将收到错误。
选择“ 角色分配 ”选项卡。
将以下角色分配给之前创建的服务主体，以访问 Microsoft Purview 中的各种数据平面。有关详细步骤，请参阅使用 Microsoft Purview 治理门户分配 Azure 角色。
- 用于访问目录数据平面的数据策展人角色。
- 用于访问扫描数据平面的数据源管理员角色。
- 集合管理员角色来访问帐户数据平面和元数据策略数据平面。
- 用于访问 DevOps 策略 API 的策略作者角色
注意

只有集合管理员角色的成员才能在 Microsoft Purview 中分配数据平面角色。有关Microsoft Purview 角色的详细信息，请参阅 Microsoft Purview 中的访问控制。

获取令牌

可以将 POST 请求发送到以下 URL 以获取访问令牌。

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

可以通过在Azure 门户中搜索租户属性来查找租户 ID。该 ID 将在租户属性页上提供。

需要将以下参数传递到上述 URL：

client_id：在 Microsoft Entra ID 中注册并分配给 Microsoft Purview 帐户的数据平面角色的应用程序的客户端 ID。
client_secret：为上述应用程序创建的客户端密码。
grant_type：这应该是“client_credentials”。
资源：“https://purview.azure.net”

下面是 PowerShell 中的 POST 请求示例：

$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 。
确保软件是用于发送 POST 请求的应用程序的最新软件。

使用上面的访问令牌调用数据平面 API。

后续步骤

Microsoft Purview 数据平面 REST API 管理数据源

通过