使用 REST API 创建资产

本教程介绍如何在 Microsoft Purview 数据映射中创建用户能够在 Microsoft Purview 统一目录中搜索和浏览的资产。

如果已有服务主体和身份验证令牌,可以直接跳到使用 REST API 创建资产的 步骤。 否则,请按照本指南调用 REST API。

先决条件

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

要让 REST API 客户端能够访问 Microsoft Purview 以创建实体,该客户端必须拥有一个服务主体(应用程序)和一个 Microsoft Purview 所识别并配置为可信任的身份。

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

创建新的服务主体:

  1. 登录 Azure 门户

  2. 在门户中,搜索并选择“Microsoft Entra ID”。

  3. 在“Microsoft Entra ID”页中,从左窗格中选择“应用注册”。

  4. 选择“新注册”。

  5. 在“注册应用程序”页面上:

    1. 为应用程序输入名称(服务主体名称)。
    2. 选择“仅此组织目录中的帐户(仅 <租户名称> - 单个租户)”。
    3. 对于“重定向 URI (可选)”,选择“Web”并输入一个值 。 此值无需是有效的终结点。 使用 https://exampleURI.com 即可。
    4. 选择“注册” 。
  6. 在“新建服务主体”页上,复制“显示名称”和“应用程序(客户端) ID”的值,保存供稍后使用 。

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

要使用服务主体(应用程序),需要知道服务主体的密码:

  1. 应用注册列表中选择服务主体(应用程序)。
  2. 从左窗格中选择“证书和机密”
  3. 选择“新建客户端机密”。
  4. 在“客户端机密”页面上,输入“说明”,在“过期”下选择一个过期时间,然后选择“添加” 。
  5. 在“客户端机密”页上,新机密的“值”列中的字符串就是你的密码 。 保存此值。

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

创建新的服务主体后,需要分配权限,以便服务主体可以访问 Microsoft Purview 帐户。 需要分配的权限取决于使用的是 经典 Microsoft Purview 体验 还是 新 Microsoft Purview 门户

选择正在使用的体验选项卡。

  1. 导航到使用 Microsoft Purview 治理门户

  2. 在左侧菜单中选择“数据映射”。

  3. 选择“集合”。

  4. 在“集合”菜单中选择根集合。 这是列表中的顶级集合,并将与你的 Microsoft Purview 帐户同名。

    注意

    还可以将服务主体权限分配给任何子集合,而不是根集合。 但是,所有 API 的作用域都将为该集合(及继承权限的子集合),且尝试对其他集合调用 API 的用户将收到错误。

  5. 选择“角色分配”选项卡。

  6. 将“数据管理员”角色分配给之前创建的服务主体。 有关详细步骤,请参阅使用 Microsoft Purview 治理门户分配 Azure 角色

分配权限后,需要收集身份验证令牌。

  1. 以下 URL 发送 POST 请求以获取访问令牌:

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

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

    需要向上述 URL 传递以下参数:

    • client_id:在 Microsoft Entra ID 中注册的应用程序的客户端 ID,分配给 Microsoft Purview 帐户的数据平面角色。
    • client_secret:为上述应用程序创建的客户端密码。
    • grant_type:此参数应该为“client_credentials”。
    • resource:此参数应该为“https://purview.chinacloudapi.cn”

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

    $tenantID = "12a345bc-67d1-ef89-abcd-efg12345abcde"
    
    $url = "https://login.partner.microsoftonline.cn/$tenantID/oauth2/token"
    $params = @{ client_id = "a1234bcd-5678-9012-abcd-abcd1234abcd"; client_secret = "abcd~a1234bcd56789012abcdabcd1234abcd"; grant_type = "client_credentials"; resource = ‘https://purview.chinacloudapi.cn’ }
    
    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.chinacloudapi.cn",
        "access_token": "<<access token>>"
    }
    

    提示

    如果收到一条错误消息称:仅“单页应用程序”客户端类型允许跨域令牌兑换。

    • 请检查请求标头并确认请求 包含“origin”标头。
    • 确认重定向 URI 已设置为服务主体中的Web。
    • 确保用于发送 POST 请求的应用程序的软件是最新的。
  2. 使用上面的访问令牌来调用数据平面 API。

使用 REST API 创建资产

现在,你已拥有令牌并可以进行身份验证,现在可以创建资产了。

重要

你的请求 URL 端点取决于使用的 Microsoft Purview 体验:经典 Microsoft Purview 体验新 Microsoft Purview 门户网站

创建 Azure 资产

以下示例可用于为 Azure 资源创建实体。 此示例涵盖 Azure 存储帐户,但可以将它用于任何其他 Azure 源。

重要

若要将此示例用于 Azure 资源,请替换有效负载中的以下值:

  • typeName
  • 所有者
  • qualifiedName
  • name
  • 专家 ID
  • 专家信息
  • 所有者 ID
  • 所有者信息
  • createdBy
  • Updatedby

请求 URL:https://{accountName}.purview.azure.cn/catalog/api/atlas/v2/entity

方法:POST

身份验证:使用上一步中的令牌作为持有者令牌。

有效负载示例:

{
  "referredEntities": {},
  "entity": {
    "typeName": "azure_storage_account",
    "attributes": {
      "owner": "ExampleOwner",
      "modifiedTime": 0,
      "createTime": 0,
      "qualifiedName": "https://exampleaccount.core.chinacloudapi.cn",
      "name": "ExampleStorageAccount",
      "description": null,
      "publicAccessLevel": null
    },
    "contacts": {
      "Expert": [
        {
          "id": "30435ff9-9b96-44af-a5a9-e05c8b1ae2d2",
          "info": "Example Expert Info"
        }
      ],
      "Owner": [
        {
          "id": " 30435ff9-9b96-44af-a5a9-e05c8b1ae2d2",
          "info": "Example Owner Info"
        }
      ]
    },
    "status": "ACTIVE",
    "createdBy": "ExampleCreator",
    "updatedBy": "ExampleUpdator",
    "version": 0
  }
}

创建多云资产

以下示例可用于为多云资源创建实体。 此示例创建一个 Snowflake 资源,但你可以将其用于任何其他源

重要

若要将此示例用于 Azure 资源,请替换有效负载中的以下值:

  • typeName
  • 所有者
  • qualifiedName
  • name
  • type
  • 专家 ID
  • 专家信息
  • 所有者 ID
  • 所有者信息
  • createdBy
  • Updatedby

请求 URL:https://{accountName}.purview.azure.cn/catalog/api/atlas/v2/entity

方法:POST

身份验证:使用上一步中的令牌作为持有者令牌。

有效负载示例:

{
  "referredEntities": {},
  "entity": {
    "typeName": "snowflake_table",
    "attributes": {
      "owner": "ExampleOwner",
      "modifiedTime": 0,
      "createTime": 0,
      "qualifiedName": "snowflake://microsoft_partner.east-us-2.azure.snowflakecomputing.com/databases/AZUREPURVIEW_TESTDB/schemas/COMPANY/tables/PROJECT_INFO",
      "name": "PROJECT_INFO",
      "description": null,
      "type": "TABLE"
    },
    "contacts": {
      "Expert": [
        {
          "id": "30435ff9-9b96-44af-a5a9-e05c8b1ae2d2",
          "info": "Example Expert Info"
        }
      ],
      "Owner": [
        {
          "id": "4b27e65f-6a15-4925-a4ef-2e640445079b",
          "info": "Example Owner Info"
        }
      ]
    },
    "status": "ACTIVE",
    "createdBy": "ExampleCreator",
    "updatedBy": "ExampleUpdator",
    "version": 0
  }
}

后续步骤