API 驅動輸入布建概念

  • 發行項

本檔提供 Microsoft Entra API 驅動輸入使用者布建的概念性概觀。

簡介

如今，企業有各種權威制度記錄。 若要建立端對端身分識別生命週期，加強安全性狀態，並遵守法規，Microsoft Entra ID 中的身分識別數據必須與這些記錄系統中受管理的員工數據保持同步。 記錄系統可以是 HR 應用程式、薪資應用程式、電子錶格，或裝載於內部部署或雲端之資料庫中的 SQL 資料表。

透過 API 驅動的輸入布建，Microsoft Entra 布建服務現在支援與 任何 記錄系統的整合。 客戶和合作夥伴可以使用 其選擇的任何 自動化工具，從記錄系統擷取員工數據，並將其內嵌至 Microsoft Entra ID。 IT 系統管理員完全控制如何使用屬性對應處理和轉換數據。 在 Microsoft Entra 識別符中提供員工數據之後，IT 系統管理員可以使用 生命週期工作流程來設定適當的 joiner-mover-leaver 商務程式。

支援的案例

使用 API 驅動的輸入布建來啟用數個輸入使用者布建案例。 此圖表示范最常見的案例。

顯示 API 工作流程案例的圖表。

案例 1：讓 IT 小組使用任何自動化工具匯入 HR 數據擷取

一般檔案、CSV 檔案和 SQL 臨時表通常用於企業整合案例。 員工、承包商和廠商資訊會定期匯出為下列其中一種格式，並使用自動化工具將此數據與企業身分識別目錄同步處理。 透過 API 導向的輸入布建，IT 小組可以使用其選擇的任何自動化工具（例如：PowerShell 腳本或 Azure Logic Apps），將這項整合現代化並簡化。

案例 2：讓 ISV 與 Microsoft Entra ID 建立直接整合

透過 API 導向的輸入布建，HR ISV 可以傳遞原生同步處理體驗，讓 HR 系統中的變更自動流入 Microsoft Entra ID，並連線 內部部署的 Active Directory 網域。 例如，HR 應用程式或學生資訊系統應用程式可以在交易完成或每日大量更新時立即將數據傳送至 Microsoft Entra ID。

案例 3：讓系統整合者能夠建立更多記錄系統的連接器

合作夥伴可以建置自定義 HR 連接器，以符合從記錄系統到 Microsoft Entra 識別碼之數據流的不同整合需求。

在上述所有案例中，整合會簡化，因為 Microsoft Entra 布建服務負責執行身分識別配置檔比較、限制數據同步至 IT 系統管理員所設定的範圍邏輯，以及執行 Microsoft Entra 系統管理中心所管理的規則型屬性流程和轉換。

端對端流程

輸入布建的端對端工作流程圖表。

工作流程的步驟

  1. IT 管理員 從 Microsoft Entra Enterprise App 資源庫設定 API 導向的輸入使用者布建應用程式。
  2. IT 管理員 授與訪問許可權，並提供 API 開發人員/合作夥伴/系統整合器的端點存取詳細數據。
  3. API 開發人員/合作夥伴/系統整合者會建置 API 用戶端，以將授權身分識別數據傳送至 Microsoft Entra ID。
  4. API 用戶端會從授權來源讀取身分識別數據。
  5. API 用戶端會傳送 POST 要求，以布 建 /bulkUpload 與布建應用程式相關聯的 API 端點。

    注意

    API 用戶端不需要執行來源屬性與目標屬性值之間的任何比較，以判斷要叫用的作業 （create/update/enable/disable）。 這會自動由布建服務處理。 API 用戶端只要使用SCIM架構建構將識別數據封裝為大量要求，即可上傳從來源系統讀取的身分識別數據。

  6. 如果成功， Accepted 202 Status 則會傳回 。
  7. Microsoft Entra 布建服務會處理收到的數據、套用屬性對應規則，以及完成使用者布建。
  8. 根據所設定的布建應用程式，用戶會布建到 內部部署的 Active Directory（適用於混合式使用者）或 Microsoft Entra ID（僅限雲端使用者）。
  9. 然後，API 用戶端會查詢布建記錄 API 端點，以取得傳送之每個記錄的狀態。
  10. 如果處理任何記錄失敗，API 用戶端可以檢查錯誤詳細數據，並在下一個大量要求中包含對應至失敗作業的記錄（步驟 5）。
  11. IT 管理員 可以隨時檢查布建作業的狀態，並在布建記錄中檢視事件。

API 驅動輸入使用者布建的主要功能

  • 作為布建應用程式，可公開 使用有效 OAuth 令牌存取的異步 Microsoft Graph 布 建 /bulkUpload API 端點。
  • 租用戶系統管理員必須授與與此布建應用程式互動的 API 用戶端 Graph 許可權 SynchronizationData-User.Upload。
  • 圖形 API 端點會使用 SCIM 架構建構接受有效的大量要求承載。
  • 透過 SCIM 架構延伸模組，您可以在大量要求承載中傳送任何屬性。
  • 輸入布建 API 的速率限制是每秒 40 個大量上傳要求。 每個大量要求最多可以包含50筆用戶記錄，從而支援每秒2000筆記錄的上傳速率。
  • 每個 API 端點都會與 Microsoft Entra 識別碼中的特定布建應用程式相關聯。 您可以為每個資料源建立布建應用程式，以整合多個數據源。
  • 傳入大量要求承載會以近乎即時的方式處理。
  • 管理員 可以藉由檢視布建記錄來檢查布建進度。
  • API 用戶端可以查詢 布建記錄 API 來追蹤進度。

授權需求

這項功能適用於 Microsoft Entra ID P1、P2 和 Microsoft Entra ID 控管 授權。 若要尋找您需求的正確授權，請參閱 Microsoft Entra ID 控管 授權基本概念。

API 使用指引

/bulkUpload API 端點會展開您可以在 Entra ID 中管理使用者的方式數目。 若要協助您判斷 API 端點是否 /bulkUpload 適合您的整合案例，請參閱此數據表來比較它與其他以 API 為基礎的整合選項。

使用案例與 API 的對應 使用者建立 API HR 輸入大量 API 用戶邀請 API 直接指派 API
當您的身分識別建立案例為... 針對 HR 來源中未與任何背景工作角色相關聯的使用者，在 Entra ID 中建立臨機操作使用者 從權威 HR 來源採購員工記錄，而您希望這些員工在 Entra 標識碼或 內部部署的 Active Directory 中擁有「成員」帳戶 在 Entra ID 中建立臨機操作來賓使用者，以供共用之用，其中來賓具有唯一訪問許可權 現有使用者的存取指派，以及在 Entra ID 中建立來賓，以提供新的來賓標準化存取權
...使用 API... 建立使用者 執行 bulkUpload。 建立邀請 建立 accessPackageAssignmentRequest
產生的使用者會先在中建立... Entra ID 內部部署 Active Directory 或 Entra 識別碼 Entra ID Entra ID
產生的使用者會向... Entra ID，其中包含您提供的密碼 Entra標識符的內部部署 Active Directory，具有 Entra 生命週期工作流程提供的暫時存取傳遞 主租使用者或其他身分識別提供者 主租使用者或其他身分識別提供者
用戶後續的更新可以透過 圖形 API 或 Entra 入口網站 圖形 API 或 HR 輸入大量 API 或 Entra 入口網站 圖形 API 或 Entra 入口網站 圖形 API 或 Entra 入口網站
使用者僱用開始時的生命週期取決於... 手動程式 根據屬性觸發employeeHireDate的進入生命週期工作流程 權利管理 使用權利管理存取套件自動指派
使用者僱用終止時的生命週期取決於... 手動程式 根據屬性觸發employeeLeaveDateTime的下線生命週期工作流程 存取權檢閱 當使用者失去最後一個存取套件指派時的權利管理，就會將其移除
# 學習目標 指引
1. 您要深入瞭解輸入布建 API 規格。 請參閱 /bulkUpload API 規格檔。
2. 您想要更熟悉 API 驅動的布建概念、案例和限制。 請參閱 API 驅動輸入布建的常見問題。
3. 身為 管理員 使用者，您想要快速測試輸入布建 API。 * 建立 API 驅動輸入布建應用程式
* 使用 Graph 總管測試 API
4. 使用服務帳戶或受控識別，您想要快速測試輸入布建 API。 * 建立 API 驅動輸入布建應用程式
* 授與 API 許可權
* 使用 cURL 或 Postman 測試 API
5. 您想要擴充 API 驅動布建應用程式，以處理更多自定義屬性。 請參閱擴充 API 驅動布建以同步處理自訂屬性的教學課程
6. 您要將資料從記錄系統自動上傳至輸入布建 API 端點。 請參閱教學課程
* PowerShell 快速入門
* Azure Logic Apps 快速入門
7. 您要針對輸入布建 API 問題進行疑難解答 請參閱疑難解答指南。

外部學習資源

我們的合作夥伴和 Microsoft MP 所建立的下列內容提供如何部署和設定各種整合案例的 API 驅動布建的額外指引。

下一步