閱讀英文

共用方式為


使用 REST API 建立資產

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

注意

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

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

必要條件

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

若要讓 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. 流覽至您的 Microsoft Purview 治理入口網站

  2. 選取左側選單中的 [數據對應]。

  3. 選取 [集合]。

  4. 選取 [集合] 功能表中的根集合。 這是清單中的頂端集合,且名稱會與您的 Microsoft Purview 帳戶相同。

    注意

    您也可以將服務主體許可權指派給任何子集合,而不是根集合。 不過,所有 API 的範圍都會限於該集合 (和繼承許可權) 的子集合,而嘗試為另一個集合呼叫 API 的使用者將會收到錯誤。

  5. 選取 [ 角色指派] 索引標籤

  6. 將數據編者角色指派給先前建立的服務主體。 如需詳細步驟,請 參閱使用 Microsoft Purview 治理入口網站指派 Azure 角色

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

  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 建立資產

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

重要

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

建立 Azure 資產

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

重要

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

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

要求 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

要求 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
  }
}

後續步驟