使用 REST API 建立資產

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

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

必要條件

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

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

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

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

若要建立新的服務主體：

1. 登入 Azure 入口網站。

2. 從入口網站中，搜尋並選取 [Microsoft Entra ID]。

3. 從 [Microsoft Entra ID] 頁面，從左窗格中選取 [應用程式註冊]。

4. 選取 [新增註冊]。

5. 在 [ 註冊應用程式] 頁面上：

   1. (服務主體名稱) 輸入應用程式的 [名稱]。
   2. 選擇 此組織目錄中的 [帳戶僅 (<您的租使用者名稱> - 單一租使用者) 。
   3. 針對 [重新導向 URI] (選用) ，選取 [Web ] 並輸入值。 此值不需要是有效的端點。 https://exampleURI.com 會執行。
   4. 選取 [登錄]。

6. 在新的服務主體頁面上，複製 [顯示名稱 ] 和 [應用程式 (用戶端) 標識 符的值，以供稍後儲存。

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

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

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

使用服務主體設定驗證

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

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

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

1. 將 POST 要求傳送至下列 URL 以取得存取權杖：

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

   您可以在 Azure 入口網站 中搜尋租用戶屬性，以尋找您的租用戶標識碼。 此標識碼可在租用戶屬性頁面上取得。

   下列參數必須傳遞至上述 URL：

   • client_id：在 Microsoft Entra ID 中註冊的應用程式用戶端標識符，並指派給 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 。
   • 針對您用來傳送 POST 要求的應用程式，請確定您的軟體是最新的。

2. 使用上述存取令牌來呼叫數據平面 API。

使用 REST API 建立資產

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

建立 Azure 資產

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

方法：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 資源，但您可以將它用於任何其他來源

方法：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
  }
}

後續步驟