重要事項
先前Azure Purview) (Microsoft Purview 整合式目錄 和傳統 Microsoft Purview 資料控管功能即將淘汰。 Microsoft 正在 Microsoft Fabric 中合併其資料控管功能。 您無法再建立新帳戶,現有功能將維持在維護模式,直到 2027 年 11 月 12 日為止。 如需淘汰時間表、轉換指引,以及建議的後續步驟,請參閱 Microsoft Purview 資料控管淘汰公告。
在本教學課程中,您將了解如何驗證 Microsoft Purview 資料平面 API。 任何想要向 Microsoft Purview 提交資料、將 Microsoft Purview 納入自動化程式的一部分,或在 Microsoft Purview 上建立自己的使用者體驗的人,都可以使用 API 來執行此操作。
必要條件
- 若要開始使用,您必須擁有現有的 Microsoft Purview 帳戶。 如果您沒有目錄,請參閱 建立 Microsoft Purview 帳戶的快速入門。
建立服務主體 (應用程式)
若要讓 API 用戶端存取 Microsoft Purview 資料平面 API,用戶端必須具有服務主體 (應用程式) ,以及 Microsoft Purview 可辨識並設定為信任的身分識別。 當您進行 API 呼叫時,該服務主體的身分識別將用於授權。
使用現有服務主體 (應用程式識別碼的客戶) 失敗率很高。 因此,建議您建立新的服務主體來呼叫 API。
若要建立新的服務主體:
登入 Azure 入口網站。
從入口網站中,搜尋並選取 Microsoft Entra ID。
在 Microsoft Entra ID 頁面中,從左窗格中選取 [應用程式註冊]。
選取 [新增註冊]。
在 [註冊應用程式] 頁面上:
- 輸入應用程式的 名稱 (服務主體名稱) 。
- 在 [ 誰可以使用此應用程式或存取此 API?] 中,選取您預期使用此 API 的使用者帳戶類型。
提示
如果您期望只有目前Microsoft Entra ID租用戶中的使用者使用 REST API,請選取 [僅限此組織目錄中的帳戶] (<租用戶的名稱> - 單一租用戶) 。 否則,請考慮其他選項。
- 針對 [重新導向 URI (選擇性) ] ,選取 [網路 ] 並輸入值。 此值不需要是有效的端點。
https://exampleURI.com會的。 - 選取 [登錄]。
在 [新增服務主體] 頁面上,複製 [ 顯示名稱 ] 和 [應用程式 (用戶端) 識別碼 ] 的值,以儲存以供日後使用。
應用程式識別碼是
client_id範例程式碼中的值。
若要使用服務主體 (應用程式) ,您必須知道服務主體的密碼,可以透過以下方式找到:
在 Azure 入口網站中,搜尋並選取 Microsoft Entra ID,然後從左側窗格選取 [應用程式註冊]。
從清單中選取您的服務主體 (應用程式) 。
從左側窗格中選取 [憑證 & 密碼 ]。
選取 [新用戶端密碼]。
在 [新增用戶端密碼 ] 頁面上,輸入 描述,在 [ 到期日] 底下選取到期時間,然後選取 [新增]。
在 [用戶端密碼 ] 頁面上,新密碼的 [值 ] 資料行中的字串就是您的密碼。 儲存此值。
使用服務主體設定驗證
建立新的服務主體之後,您必須將 Purview 帳戶的資料平面角色指派給上述建立的服務主體。 請遵循下列步驟來指派正確的角色,以在服務主體與 Purview 帳戶之間建立信任:
瀏覽至您的 Microsoft Purview 管理入口網站。
選取左側功能表中的 [資料對應]。
選取集錦。
在集合功能表中選取根集合。 這將會是清單中的頂端集合,且與您的 Microsoft Purview 帳戶具有相同的名稱。
注意事項
您也可以將服務主體權限指派給任何子集合,而不是根集合。 不過,所有 API 的範圍都限定為該集合 (和繼承權限) 的子集合,而嘗試呼叫另一個集合之 API 的使用者將會收到錯誤。
選取 [角色分配] 索引標籤。
將下列角色指派給先前建立的服務主體,以存取 Microsoft Purview 中的各種資料平面。 如需詳細步驟,請參閱使用 Microsoft Purview 治理入口網站指派 Azure 角色。
存取目錄資料平面的資料管理者角色。
用於存取掃描資料平面的資料來源系統管理員角色。
存取帳戶資料平面和中繼資料原則資料平面的集合管理員角色。
存取 DevOps 原則 API 的原則作者角色
注意事項
只有集合管理員角色的成員才能在 Microsoft Purview 中指派資料平面角色。 如需 Microsoft Purview 角色的詳細資訊,請參閱 Microsoft Purview 中的存取控制。
取得權杖
您可以傳送 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'。
- 資源: 'https://purview.azure.net'
以下是 PowerShell 中的 POST 要求範例:
$tenantID = "12a345bc-67d1-ef89-abcd-efg12345abcde"
$url = "https://login.microsoftonline.com/$tenantID/oauth2/token"
$params = @{ client_id = "00001111-aaaa-2222-bbbb-3333cccc4444"; 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>>"
}
提示
如果您收到下列錯誤訊息: 只有「單頁應用程式」用戶端類型才允許跨原始來源權杖兌換。
- 檢查您的要求標頭,並確認您的要求 不 包含 'origin' 標頭。
- 確認您的重新導向 URI 已在服務主體中設定為 web 。
- 請確定您的軟體是最新狀態,以供您用來傳送 POST 要求的應用程式使用。
使用上述的存取權杖來呼叫資料平面 API。