教學課程：使用 REST API

發行項
08/23/2023

在本教學課程中，您將瞭解如何使用 Microsoft Purview 資料平面 REST API。任何想要將資料提交至 Microsoft Purview、在自動化程式中包含 Microsoft Purview，或在 Microsoft Purview 上建置自己的使用者體驗的人，都可以使用 REST API 來執行這項操作。

如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。

必要條件

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

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

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

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

若要建立新的服務主體：

登入 Azure 入口網站。
從入口網站中，搜尋並選取 [Azure Active Directory]。
從[Azure Active Directory]頁面，從左窗格中選取 [應用程式註冊]。
選取 [新增註冊]。
在 [ 註冊應用程式] 頁面上：
1. (服務主體名稱) 輸入應用程式的 [名稱]。
2. 選取此組織目錄中的 [帳戶僅 (< 您的租使用者名稱 > - 單一租使用者) 。
3. 針對 [重新導向 URI] (選用) ，選取 [Web ] 並輸入值。此值不需要是有效的端點。 https://exampleURI.com 會執行。
4. 選取 [登錄]。
在新的服務主體頁面上，複製 [顯示名稱 ] 和 [應用程式 (用戶端) 標識 符的值，以供稍後儲存。

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

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

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

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

使用服務主體設定驗證

建立新的服務主體之後，您必須將 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：在 Azure Active Directory 中註冊並指派給 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 。
如果您使用 Postman 之類的應用程式，請確定您的軟體是最新狀態。

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

後續步驟

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