教學課程：驗證 API

在本教學課程中，您將瞭解如何驗證 Microsoft Purview 資料平面 API。 任何想要將數據提交至 Microsoft Purview、將 Microsoft Purview 納入自動化程式的一部分，或在 Microsoft Purview 上建置自己的使用者體驗的人都可以使用 API 來執行此動作。

必要條件

• 若要開始使用，您必須擁有現有的 Microsoft Purview 帳戶。 如果您沒有目錄，請參閱 建立 Microsoft Purview 帳戶的快速入門。

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

若要讓 API 用戶端存取Microsoft Purview 資料平面 API，用戶端必須具有服務主體 (應用程式) ，以及 Purview Microsoft辨識並設定為信任的身分識別。 當您進行 API 呼叫時，將會使用該服務主體的身分識別進行授權。

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

若要建立新的服務主體：

1. 登入 Azure 入口網站。

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

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

4. 選取 [新增註冊]。

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

   1. 輸入應用程式的 名稱 (服務主體名稱) 。
   2. 針對 [誰可以使用此應用程式或存取此 API？]，選取您預期使用此 API 的使用者帳戶類型。

      提示

      如果您預期目前 Microsoft Entra ID 租使用者中的使用者只能使用 REST API，請選取 [此組織目錄中的帳戶 ] 僅 (<租用戶名稱> - 單一租用戶) 。 否則，請考慮其他選項。

   3. 針對 [重新導向 URI (選用) ] ，選取 [網頁 ]，然後輸入值。 此值不需要是有效的端點。 https://exampleURI.com 行。
   4. 選取 [登錄]。

   

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

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

   

若要使用服務主體 (應用程式) ，您必須知道服務主體的密碼，可透過下列方式找到：

1. 從 Azure 入口網站 中，搜尋並選取 Microsoft Entra ID，然後從左窗格選取 [應用程式註冊]。

2. 從清單中選取您的服務主體 (應用程式) 。

3. 從左窗格中選取憑證 & 秘密 。

4. 選取 [新用戶端密碼]。

5. 在 [ 新增用戶端密碼 ] 頁面上，輸入 [描述]，在 [到期] 底下選取到期時間，然後選取 [ 新增]。

   在 [用戶端密碼 ] 頁面上，新密碼的 [值] 欄中的字串是您的密碼。 儲存此值。

   

使用服務主體設定驗證

建立新的服務主體之後，您必須將 Purview 帳戶的資料平面角色指派給上面建立的服務主體。 請遵循下列步驟來指派正確的角色，以在服務主體與 Purview 帳戶之間建立信任：

資料圖

1. 流覽至您的 Microsoft Purview 治理入口網站。

2. 選取左側功能表中的資料對應。

3. 選取 [集合]。

4. 在集合功能表中選取根集合。 這將是清單中的頂端集合，而且會與您的 Microsoft Purview 帳戶具有相同的名稱。

   注意事項

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

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

6. 將下列角色指派給先前建立的服務主體，以存取 Microsoft Purview 中的各種資料平面。 如需詳細步驟，請參閱 使用 Microsoft Purview 治理入口網站指派 Azure 角色。

• 資料策展人角色，以存取目錄資料平面。

• 資料來源管理員角色，以存取掃描資料平面。

• 收集管理員角色，以存取帳戶資料平面和中繼資料原則資料平面。

• 存取 DevOps 原則 API 的原則作者角色

  注意事項

  只有集合管理員角色的成員才能在 Microsoft Purview 中指派資料平面角色。 如需 Microsoft Purview 角色的詳細資訊，請參閱 Microsoft Purview 中的存取控制。

整合式目錄

1. 流覽至您的 Microsoft Purview 治理入口網站。
2. 在左側功能表中選取 [整合式目錄]。
3. 選取 型錄管理> 控管網域。
4. 在 [依關鍵字篩選] 中，輸入您的網域名稱，然後從搜尋結果中選取網域。
5. 選取 [角色 ] 索引標籤。
6. 將下列角色指派給先前建立的服務主體，以存取 Microsoft Purview 中的各種資料平面。 如需詳細步驟，請參閱 使用 Microsoft Purview 治理入口網站指派 Azure 角色。

• 資料目錄讀取器可存取 OKR、業務領域、關鍵資料元素、資料產品、術語。
• 資料管理員可存取 OKR、業務領域、關鍵資料元素、資料產品、條款、原則。
• 數據產品擁有者可存取 OKR、商務網域、重要數據元素、數據產品、條款、原則。
• 治理網域建立者，以存取商務網域。
• 治理網域擁有者可存取「商業網域」、「原則」。

取得代幣

您可以將 POST 請求傳送到以下 URL 以獲取訪問令牌。

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

您可以在 Azure 入口網站 中搜尋租用戶屬性，以尋找您的租用戶識別碼。 該 ID 將在租用戶屬性頁面上提供。

需要將以下參數傳遞到上述網址：

• client_id：在 Microsoft Entra ID 中註冊的應用程式用戶端識別碼，並指派給 Microsoft Purview 帳戶的資料平面角色。
• client_secret：為上述應用程式建立的用戶端密碼。
• grant_type：這應該是“client_credentials”。
• 資源： '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>>"
    }

提示

如果您收到錯誤訊息，內容為： 僅允許「單頁應用程式」用戶端類型進行跨來源權杖兌換。

• 檢查您的請求標頭並確認您的請求 不 包含「來源」標頭。
• 確認您的重新導向 URI 已在服務主體中設定為 Web 。
• 請確定您的軟體是最新的，適用於您用來傳送 POST 要求的應用程式。

使用上述存取權杖來呼叫資料平面 API。

後續步驟

管理資料來源Microsoft Purview 資料平面 REST API