API 驅動的輸入佈建概念
本文件提供 Microsoft Entra API 驅動的輸入使用者佈建概念性概觀。
簡介
如今，企業有各種的授權記錄系統。 若要建立端對端身分識別生命週期，請加強安全性狀態，並符合法規，Microsoft Entra ID 中的身分識別資料必須與這些記錄系統中管理的員工資料保持同步。 系統記錄可能是 HR 應用程式、薪資應用程式、試算表，或裝載於內部部署或雲端之資料庫中的 SQL 資料表。
透過 API 驅動的輸入佈建，Microsoft Entra 佈建服務現在支援與任何記錄系統的整合。 客戶和合作夥伴可以使用自選的任何自動化工具，從記錄中的系統擷取員工資料，並將其內嵌至 Microsoft Entra ID。 IT 系統管理員可完全控制如何使用屬性對應來處理並轉換資料。 Microsoft Entra ID 中提供員工資料之後，IT 系統管理員可以使用生命週期工作流程來設定適當的入職者-調職者-離職者商務流程。
支援的案例
使用 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 ID 之資料串流的不同整合需求。
在上述所有案例中，整合會簡化，因為 Microsoft Entra 佈建服務會負責執行身分識別設定檔比較、限制資料同步至 IT 系統管理員所設定的範圍邏輯，以及執行 Microsoft Entra 系統管理中心所管理的規則型屬性流程和轉換。
端對端流程
工作流程的步驟
- IT 系統管理員會從 Microsoft Entra Enterprise App 資源庫設定 API 驅動的輸入使用者佈建應用程式。
- IT 系統管理員授與存取權限，並提供 API 開發人員/合作夥伴/系統整合器的端點存取詳細資料。
- API 開發人員/合作夥伴/系統整合者會建置 API 用戶端，以將授權身分識別資料傳送至 Microsoft Entra ID。
- API 用戶端會從授權來源讀取身分識別資料。
- API 用戶端會傳送 POST 要求，以佈建/bulkUpload 與佈建應用程式相關聯的 API 端點。
注意
API 用戶端不需要比較來源屬性與目標屬性值，以判斷要叫用的作業 (建立/升級/啟用/停用)。 佈建服務會自動處理這種情況。 API 用戶端只要使用 SCIM 結構描述建構將識別資料封裝為大量要求，即可將來源系統讀取到的身分資料上傳。
- 如果成功，則會傳回
Accepted 202 Status。 - Microsoft Entra 佈建服務會處理收到的資料、套用屬性對應規則，以及完成使用者佈建。
- 根據所設定的佈建應用程式，使用者會佈建到內部部署 Active Directory (適用於混合式使用者) 或 Microsoft Entra ID (僅限雲端使用者)。
- 然後，API 用戶端會查詢佈建記錄 API 端點，以取得每個記錄傳送的狀態。
- 如果任何記錄的處理失敗，API 用戶端可以檢查錯誤 詳細資料，並在下一個大量要求中包含對應至失敗作業的記錄 (步驟 5)。
- IT 系統管理員可以隨時檢查佈建作業的狀態，並在佈建記錄中檢視事件。
API 驅動的輸入使用者佈建主要功能
- 作為佈建應用程式，可公開使用有效 OAuth 權杖存取的非同步 Microsoft Graph 佈建 /bulkUpload API 端點。
- 租用戶系統管理員必須授與 Graph 權限
SynchronizationData-User.Upload給此佈建應用程式互動的 API 用戶端。 - 圖形 API 端點會使用 SCIM 結構描述建構接受有效的大量要求承載。
- 透過 SCIM 結構描述延伸模組，您可以在大量要求承載中傳送任何屬性。
- 輸入佈建 API 的速率上限是每秒 40 個大量上傳要求。 每個大量要求最多可以包含 50 筆使用者記錄，從而支援每秒 2,000 筆記錄的上傳速率。
- 每個 API 端點都會與 Microsoft Entra ID 中的特定佈建應用程式相關聯。 您可以為每個資料源建立佈建應用程式，以整合多個資料來源。
- 傳入大量要求承載會以近乎即時的方式處理。
- 系統管理員可以檢視佈建記錄，以檢查佈建進度。
- API 用戶端可以透過查詢佈建記錄 API 來追蹤進度。
授權需求
此功能適用於 Microsoft Entra ID P1、P2 和 Microsoft Entra ID 控管授權。 若要找到適合您需求的授權，請參閱 Microsoft Entra ID 控管授權基本概念。
API 使用指引
/bulkUpload API 端點會展開數種方式，讓您可以在 Microsoft Entra ID 中管理使用者。 若要協助您判斷 /bulkUpload API 端點是否適合您的整合案例，請參閱此表格來比較與其他以 API 為基礎的整合選項。
| 使用案例與 API 對應 | 使用者建立 API | HR 輸入大量 API | 使用者邀請 API | 直接指派 API |
|---|---|---|---|---|
| 當您的身分識別建立案例為... | 針對 HR 來源中未與任何背景工作角色相關聯的使用者，在 Microsoft Entra ID 中建立隨機使用者 | 從授權 HR 來源獲取員工記錄，而且您希望這些員工在 Microsoft Entra ID 或內部部署 Active Directory 中擁有「成員」帳戶 | 在 Microsoft Entra ID 中建立隨選來賓使用者，以供共用，其中來賓具有唯一存取權 | 現有使用者的存取指派，以及在 Microsoft Entra ID 中建立來賓 (預覽)，以提供新的來賓標準化存取權 |
| ...使用 API... | 建立使用者 | 執行 bulkUpload。 | 建立邀請 | 建立 accessPackageAssignmentRequest |
| 產生的使用者是先建立自... | Microsoft Entra ID | 內部部署 Active Directory 和 Microsoft Entra ID | Microsoft Entra ID | Microsoft Entra ID |
| 產生的使用者會驗證... | Microsoft Entra ID，其中包含您提供的密碼 | Microsoft Entra ID 的內部部署 Active Directory，具有 Entra 生命週期工作流程提供的臨時存取密碼 | 主租用戶或其他識別提供者 | 主租用戶或其他識別提供者 |
| 使用者後續的更新可以透過 | 圖形 API 或 Microsoft Entra 系統管理中心 | 圖形 API 或 HR 輸入大量 API 或 Microsoft Entra 系統管理中心 | 圖形 API 或 Microsoft Entra 系統管理中心 | 圖形 API 或 Microsoft Entra 系統管理中心 |
| 使用者就業開始時的生命週期取決... | 手動程序 | 根據 employeeHireDate 屬性觸發的 Entra 入職生命週期工作流程 |
權利管理 | 使用權利管理存取套件的自動指派 |
| 使用者雇用終止時的生命週期取決於... | 手動程序 | 根據 employeeLeaveDateTime 屬性觸發的 Entra 離職生命週期工作流程 |
存取權檢閱 | 當使用者失去最後一個存取套件指派時的權利管理，就會將其移除 |
建議學習路徑
| # | 學習目標 | 指引 |
|---|---|---|
| 1. | 深入了解輸入佈建 API 規格。 | 請參閱 /bulkUpload API 規格文件。 |
| 2. | 您想要更熟悉 API 驅動的佈建概念、案例和限制。 | 請參閱 API 驅動的輸入佈建的常見問題。 |
| 3. | 身為系統管理員使用者，您想要快速測試輸入佈建 API。 | * 建立 API 驅動的輸入佈建應用程式 * 使用 Graph 總管測試 API |
| 4. | 使用服務帳戶或受控識別，您希望能快速測試輸入佈建 API。 | * 建立 API 驅動的輸入佈建應用程式 * 授與 API 權限 * 使用 cURL 測試 API |
| 5. | 您希望能擴充 API 驅動的佈建應用程式，以處理更多自訂屬性。 | 請參閱擴充 API 驅動的佈建以同步處理自訂屬性的教學課程 |
| 6. | 您希望將資料從記錄系統自動上傳至輸入佈建 API 端點。 | 請參閱教學課程 * PowerShell 快速入門 * Azure Logic Apps 快速入門 |
| 7. | 您希望針對輸入佈建 API 問題進行疑難排解 | 請參閱疑難排解指南。 |
外部學習資源
我們的合作夥伴和 Microsoft MVP 所建立的下列內容，提供如何部署和設定各種整合案例的 API 驅動佈建的額外指導。
影片教學課程
- John Savill 解說 API 驅動佈建的運作方式
- Microsoft MVP Nick Ross 解說如何設定 API 驅動佈建
- Microsoft MVP Nick Ross 解說如何使用 Power Automate 和 API 驅動佈建，從 SharePoint 中的 Excel 檔案獲取 HR 資料
- Microsoft 合作夥伴在 API 驅動佈建上的IdentityXP 4-part 系列
部落格文章、簡報和其他實用連結
- Microsoft MVP Pim Jacob 的文章，說明如何對內部部署 Active Directory 執行 Bamboo HR API 驅動佈建
- Microsoft MVP Pim Jacob 的簡報，說明如何使用 API 驅動的佈建和生命週期工作流程設定加入者和離開者流程
- Microsoft MVP Marius Solbakken 的文章，說明如何使用 PowerShell 指令碼和 API 驅動佈獲取 Excel 資料
- Suryendu Bhattacharyya 的文章，說明如何使用自訂 GitHub Action 叫用 API 驅動佈建
- Microsoft MVP Jan Vidar Elven 的 API 驅動佈建的 Bicep 範本