使用 REST API 建立資產

發行項
08/23/2023

在本教學課程中，您將瞭解如何在使用者能夠在Microsoft Purview 資料目錄中搜尋和流覽的Microsoft Purview 資料對應中建立資產。

注意事項

如果您使用免費版本的 Microsoft Purview，只有資料編者角色群組中的使用者才能存取這些資產。

如果您已經有服務主體和驗證權杖，您可以直接跳到使用 REST API 建立資產的步驟。否則，請遵循本指南來呼叫 REST API。

必要條件

如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。
您必須擁有現有的 Microsoft Purview 帳戶。如果沒有，請檢查您的組織是否可以存取免費版本的 Microsoft Purview，或使用本快速入門來建立 Microsoft Purview 帳戶。

建立應用程式 (服務主體)

若要讓 REST API 用戶端存取 Microsoft Purview 以建立實體，用戶端必須具有服務主體 (應用程式) ，以及 Microsoft Purview 辨識並設定為信任的身分識別。

使用現有服務主體 (應用程式識別碼的客戶) 發生高失敗率。因此，建議您建立新的服務主體來呼叫 API。

若要建立新的服務主體：

登入 Azure 入口網站。
從入口網站中，搜尋並選取 [Azure Active Directory]。
從[Azure Active Directory]頁面，從左窗格中選取 [應用程式註冊]。
選取 [新增註冊]。
在 [ 註冊應用程式] 頁面上：
1. (服務主體名稱) 輸入應用程式的 [名稱]。
2. 選取此組織目錄中的 [帳戶僅 (< 您的租使用者名稱 > - 單一租使用者) 。
3. 針對 [重新導向 URI] (選用) ，選取 [Web ] 並輸入值。此值不需要是有效的端點。 https://exampleURI.com 會執行。
4. 選取 [登錄]。
在新的服務主體頁面上，複製 [顯示名稱 ] 和 [應用程式 (用戶端) 標識 符的值，以供稍後儲存。

應用程式識別碼是 client_id 範例程式碼中的值。

若要使用服務主體 (應用程式) ，您必須知道服務主體的密碼：

在應用程式註冊清單中選取您的服務主體 (應用程式) 。
從左窗格選 取 [憑證 & 秘密 ]。
選取 [新用戶端密碼]。
在 [ 新增用戶端密碼] 頁面上，輸入 [描述]，選取 [ 到期] 下的到期時間，然後選取 [ 新增]。
在 [ 用戶端密碼] 頁面上，新秘密 [ 值 ] 資料行中的字串是您的密碼。儲存此值。

使用服務主體設定驗證

建立新的服務主體之後，您必須指派許可權，您的服務主體才能存取您的 Microsoft Purview 帳戶。您需要指派的許可權取決於您使用的是傳統 Microsoft Purview 體驗或新的 Microsoft Purview 入口網站。

選取您所使用體驗的索引標籤。

傳統治理入口網站
新的 Microsoft Purview 入口網站

流覽至您的 Microsoft Purview 治理入口網站。
選取左側功能表中的 [資料對應]。
選取 [集合]。
選取 [集合] 功能表中的根集合。這是清單中的頂端集合，且名稱與您的 Microsoft Purview 帳戶相同。

注意事項

您也可以將服務主體許可權指派給任何子集合，而不是根集合。不過，所有 API 的範圍都會限於該集合 (和繼承許可權) 的子集合，而嘗試為另一個集合呼叫 API 的使用者將會收到錯誤。
選取 [ 角色指派] 索引卷 標。
將資料編者角色指派給先前建立的服務主體。如需詳細步驟，請參閱使用 Microsoft Purview 治理入口網站指派 Azure 角色。

指派許可權之後，您必須收集驗證權杖。

將 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'。
- resource：這應該是 ' 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>>"
}
```
提示

如果您收到錯誤訊息，指出： 只有'Single-Page Application' 用戶端類型才允許跨原始來源權杖兌換。
- 檢查您的要求標頭，並確認您的要求不包含 'origin' 標頭。
- 確認您的重新導向 URI 已在服務主體中設定為 Web 。
- 如果您使用 Postman 之類的應用程式，請確定您的軟體是最新狀態。
使用上述存取權杖來呼叫資料平面 API。

使用 REST API 建立資產

既然您已擁有權杖並可進行驗證，您就可以開始建立資產。

重要事項

您的要求 URL 端點取決於您使用的 Microsoft Purview 體驗：傳統 Microsoft Purview 體驗或新的 Microsoft Purview 入口網站

建立 Azure 資產

以下是您可以用來建立 Azure 資源實體的範例。此範例涵蓋 Azure 儲存體帳戶，但您可以將其用於任何其他 Azure 來源。

重要事項

若要針對您的 Azure 資源使用此範例，請取代承載中的這些值：

typeName
擁有者
qualifiedName
name
專家識別碼
專家資訊
擁有者識別碼
擁有者資訊
Createdby
Updatedby

傳統治理入口網站
新的 Microsoft Purview 入口網站

要求 URL： https://{accountName}.purview.azure.com/catalog/api/atlas/v2/entity

方法：POST

驗證：使用上一個步驟中的權杖作為持有人權杖。

承載範例：

{
  "referredEntities": {},
  "entity": {
    "typeName": "azure_storage_account",
    "attributes": {
      "owner": "ExampleOwner",
      "modifiedTime": 0,
      "createTime": 0,
      "qualifiedName": "https://exampleaccount.core.windows.net",
      "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
類型
專家識別碼
專家資訊
擁有者識別碼
擁有者資訊
Createdby
Updatedby

傳統治理入口網站
新的 Microsoft Purview 入口網站

要求 URL： https://{accountName}.purview.azure.com/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
  }
}

後續步驟

管理資料來源 Microsoft Purview 實體 REST API 參考

共用方式為

使用 REST API 建立資產

必要條件

建立應用程式 (服務主體)

使用服務主體設定驗證

使用 REST API 建立資產

建立 Azure 資產

建立多重雲端資產

後續步驟

意見反應

其他資源