本教程介绍如何对 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”页中,从左窗格中选择“应用注册”。
选择“新注册”。
在“注册应用程序”页面上:
- 输入应用程序 的名称 , (服务主体名称) 。
- 对于 “谁可以使用此应用程序或访问此 API?”,请选择希望使用此 API 的用户帐户类型。
提示
如果希望当前Microsoft Entra ID租户中的用户只能使用 REST API,请选择“此组织目录中的帐户仅 (<租户名称> - 单租户) 。 否则,请考虑其他选项。
- 对于 “重定向 URI (可选) ”,选择“ Web ”并输入值。 此值不需要是有效的终结点。
https://exampleURI.com
会的。 - 选择“注册”。
在新的服务主体页上,复制 “显示名称 ”和 “应用程序 (客户端) ID ”的值,以供以后保存。
应用程序 ID 是
client_id
示例代码中的值。
若要使用服务主体 (应用程序) ,需要知道服务主体的密码,可通过以下方式找到:
在Azure 门户中,搜索并选择“Microsoft Entra ID”,然后从左窗格中选择“应用注册”。
从列表中选择服务主体 (应用程序) 。
从左窗格中选择 “证书 & 机密 ”。
选择 新客户端密码。
在 “添加客户端密码 ”页上,输入 “说明”,在“ 过期”下选择过期时间,然后选择“ 添加”。
在 “客户端机密 ”页上,新机密的“ 值 ”列中的字符串是密码。 保存此值。
创建新的服务主体后,需要将 purview 帐户的数据平面角色分配给上面创建的服务主体。 按照以下步骤分配正确的角色,以在服务主体和 Purview 帐户之间建立信任:
在左侧菜单中选择“数据映射”。
选择“集合”。
在集合菜单中选择根集合。 该集合将是列表中的顶级集合,其名称与 Microsoft Purview 帐户的名称相同。
备注
还可以将服务主体权限分配给任何子集合,而不是根集合。 但是,所有 API 的作用域将限定为继承权限) 的集合 (和子集合,并且尝试为另一个集合调用 API 的用户将收到错误。
选择“角色分配”选项卡。
将以下角色分配给之前创建的服务主体,以访问 Microsoft Purview 中的各种数据平面。 有关详细步骤,请参阅 使用 Microsoft Purview 治理门户分配 Azure 角色。
- 用于访问目录数据平面的数据策展人角色。
- 用于访问扫描数据平面的数据源管理员角色。
- 集合管理员角色来访问帐户数据平面和元数据策略数据平面。
- 用于访问 DevOps 策略 API 的策略作者角色
备注
只有集合管理员角色的成员才能在 Microsoft Purview 中分配数据平面角色。 有关Microsoft Purview 角色的详细信息,请参阅 Microsoft Purview 中的访问控制。
可以将 POST 请求发送到以下 URL 以获取访问令牌。
https://login.partner.microsoftonline.cn/{your-tenant-id}/oauth2/v2.0/token
可以通过在Azure 门户中搜索租户属性来查找租户 ID。 该 ID 将在租户属性页上提供。
需要将以下参数传递到上述 URL:
- client_id:在 Microsoft Entra ID 中注册并分配给 Microsoft Purview 帐户的数据平面角色的应用程序的客户端 ID。
- client_secret:为上述应用程序创建的客户端密码。
- grant_type:这应该是“client_credentials”。
- 范围:“https://purview.azure.net/.default”
下面是 PowerShell 中的 POST 请求示例:
$tenantID = "12a345bc-67d1-ef89-abcd-efg12345abcde"
$url = "https://login.partner.microsoftonline.cn/$tenantID/oauth2/v2.0/token"
$params = @{ client_id = "a1234bcd-5678-9012-abcd-abcd1234abcd"; client_secret = "abcd~a1234bcd56789012abcdabcd1234abcd"; grant_type = "client_credentials"; scope = ‘https://purview.azure.net/.default’ }
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",
"scope = https://purview.azure.net/.default",
"access_token": "<<access token>>"
}
提示
如果收到如下错误消息: 仅允许“单页应用程序”客户端类型进行跨域令牌兑换。
- 检查请求标头并确认请求 不包含 “origin”标头。
- 确认重定向 URI 在服务主体中设置为 Web 。
- 确保软件是用于发送 POST 请求的应用程序的最新软件。
使用上面的访问令牌调用数据平面 API。