教學課程：驗證 API

發行項
11/13/2024

在本教學課程中，您將瞭解如何驗證 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] 頁面，從左窗格中選取 [應用程式註冊]。
選取 [新增註冊]。
在 [ 註冊應用程式] 頁面上：
1. (服務主體名稱) 輸入應用程式的 [名稱]。
2. 針對 [誰可以使用此應用程式或存取此 API？]，選取您預期使用此 API 的使用者帳戶類型。
  
  提示
  
  如果您預期只有目前 Microsoft Entra ID 租使用者的使用者使用 REST API，請選擇 [此組織目錄中的帳戶僅 (<您的租使用者名稱> - 單一租使用者) 。否則，請考慮其他選項。
3. 針對 [重新導向 URI] (選用) ，選取 [Web ] 並輸入值。此值不需要是有效的端點。 https://exampleURI.com 會執行。
4. 選取 [登錄]。
在新的服務主體頁面上，複製 [顯示名稱 ] 和 [應用程式 (用戶端) 標識 符的值，以供稍後儲存。

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

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

從 Azure 入口網站中，搜尋並選取 [Microsoft Entra ID]，然後從左窗格中選取 [應用程式註冊]。
從清單中選取您的服務主體 (應用程式) 。
從左窗格 中選取 [憑證 & 秘密 ]。
選取 [新用戶端密碼]。
在 [ 新增客戶端密碼] 頁面上，輸入 [描述]，選取 [ 到期] 下的到期時間，然後選取 [ 新增]。

在 [ 客戶端密碼] 頁面上，新秘密 [ 值 ] 資料行中的字串是您的密碼。儲存此值。

使用服務主體設定驗證

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

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

注意事項

您也可以將服務主體許可權指派給任何子集合，而不是根集合。不過，所有 API 的範圍都會限於該集合 (和繼承許可權) 的子集合，而嘗試為另一個集合呼叫 API 的使用者將會收到錯誤。
選取 [ 角色指派] 索引標籤 。
將下列角色指派給先前建立的服務主體，以存取 Microsoft Purview 中的各種數據平面。如需詳細步驟，請參閱使用 Microsoft Purview 治理入口網站指派 Azure 角色。
- 用來存取目錄數據平面的數據編者角色。
- 存取掃描數據平面的數據源系統管理員角色。
- 集合管理員存取帳戶數據平面和元數據原則數據平面的角色。
- 存取DevOps原則 API 的原則作者角色
注意事項

只有集合管理員角色的成員可以在 Purview 中指派數據平面角色Microsoft。如需 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』。
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 要求的應用程式，請確定您的軟體是最新的。

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

後續步驟

管理 Purview 數據平面 REST API Microsoft數據源

共用方式為