本文件提供 Microsoft Entra API 驅動的輸入使用者佈建概念性概觀。
Introduction
如今，企業有各種的授權記錄系統。 若要建立端對端身分識別生命週期，請加強安全性狀態，並符合法規，Microsoft Entra ID 中的身分識別資料必須與這些記錄系統中管理的員工資料保持同步。 系統記錄可能是 HR 應用程式、薪資應用程式、試算表，或裝載於內部部署或雲端之資料庫中的 SQL 資料表。
With API-driven inbound provisioning, the Microsoft Entra provisioning service now supports integration with any system of record. Customers and partners can use any automation tool of their choice to retrieve workforce data from the system of record and ingest it into Microsoft Entra ID. IT 系統管理員可完全控制如何使用屬性對應來處理並轉換資料。 Once the workforce data is available in Microsoft Entra ID, the IT admin can configure appropriate joiner-mover-leaver business processes using Lifecycle Workflows.
Supported scenarios
使用 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 系統管理中心所管理的規則型屬性流程和轉換。
End-to-end flow
工作流程的步驟
- IT 系統管理員會從 Microsoft Entra Enterprise App 資源庫設定 API 驅動的輸入使用者佈建應用程式。
- IT 系統管理員授與存取權限，並提供 API 開發人員/合作夥伴/系統整合器的端點存取詳細資料。
- API 開發人員/合作夥伴/系統整合者會建置 API 用戶端，以將授權身分識別資料傳送至 Microsoft Entra ID。
- API 用戶端會從授權來源讀取身分識別資料。
- The API client sends a POST request to provisioning /bulkUpload API endpoint associated with the provisioning app.
Note
API 用戶端不需要比較來源屬性與目標屬性值，以判斷要叫用的作業 (建立/升級/啟用/停用)。 佈建服務會自動處理這種情況。 API 用戶端只要使用 SCIM 結構描述建構將識別資料封裝為大量要求，即可將來源系統讀取到的身分資料上傳。
- 如果成功，則會傳回
Accepted 202 Status。 - Microsoft Entra 佈建服務會處理收到的資料、套用屬性對應規則，以及完成使用者佈建。
- 根據所設定的佈建應用程式，使用者會佈建到內部部署 Active Directory (適用於混合式使用者) 或 Microsoft Entra ID (僅限雲端使用者)。
- 然後，API 用戶端會查詢佈建記錄 API 端點，以取得每個記錄傳送的狀態。
- 如果任何記錄的處理失敗，API 用戶端可以檢查錯誤 詳細資料，並在下一個大量要求中包含對應至失敗作業的記錄 (步驟 5)。
- IT 系統管理員可以隨時檢查佈建作業的狀態，並在佈建記錄中檢視事件。
API 驅動的輸入使用者佈建主要功能
- Available as a provisioning app that exposes an asynchronous Microsoft Graph provisioning /bulkUpload API endpoint accessed using valid OAuth token.
- 租使用者系統管理員必須授與與此佈建應用程式互動的 API 用戶端圖形權限
SynchronizationData-User.Upload、SynchronizationData-User.Upload.OwnedBy（適用於 ISV）和ProvisioningLog.Read.All。 - 圖形 API 端點會使用 SCIM 結構描述建構接受有效的大量要求承載。
- 透過 SCIM 結構描述延伸模組，您可以在大量要求承載中傳送任何屬性。
-
/bulkUploadAPI 端點會強制執行下列節流限制：- 在任何 5 秒的視窗中，有 40 個 API 呼叫的限制。 如果超過此閾值，服務會傳回 HTTP 429 （太多要求） 回應。 若要避免節流，請在用戶端中實作步調邏輯以縮小要求空間，例如在提交之間新增延遲或速率限制處理。
- 在 Entra ID P1/P2 授權下，租用戶層級限制為每 24 小時 24 小時呼叫 2,000 個 API 呼叫，以及 Entra ID Governance 授權下的 6,000 個 API 呼叫。 超過這些限制會導致 HTTP 429 （要求太多） 回應。 若要保持在配額內，請確定您的 SCIM 大量承載已優化，以便每個 API 呼叫最多包含 50 個作業。
- 每個 API 端點都會與 Microsoft Entra ID 中的特定佈建應用程式相關聯。 您可以為每個資料源建立佈建應用程式，以整合多個資料來源。
- 傳入大量要求承載會以近乎即時的方式處理。
- Admins can check provisioning progress by viewing the provisioning logs.
- API 用戶端可以透過查詢佈建記錄 API 來追蹤進度。
License requirements
此功能適用於 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... | Create user | Perform bulkUpload. | Create invitation | Create 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 系統管理中心 |
| 使用者就業開始時的生命週期取決... | Manual processes | 根據 屬性觸發的 employeeHireDate |
Entitlement management | Automatic assignment using Entitlement management access packages |
| 使用者雇用終止時的生命週期取決於... | Manual processes | 根據 屬性觸發的 employeeLeaveDateTime |
Access reviews | 當使用者失去最後一個存取套件指派時的權利管理，就會將其移除 |
建議學習路徑
| # | Learning objective | Guidance |
|---|---|---|
| 1. | 深入了解輸入佈建 API 規格。 | Refer to /bulkUpload API spec document. |
| 2. | 您想要更熟悉 API 驅動的佈建概念、案例和限制。 | 請參閱 API 驅動的輸入佈建的常見問題。 |
| 3. | As an Admin user, you want to quickly test the inbound provisioning API. | * 建立 API 驅動的輸入佈建應用程式 * 使用 Graph 總管測試 API |
| 4. | 使用服務帳戶或受控識別，您希望能快速測試輸入佈建 API。 | * 建立 API 驅動的輸入佈建應用程式 * Grant API permissions * 使用 cURL 測試 API |
| 5. | 您希望能擴充 API 驅動的佈建應用程式，以處理更多自訂屬性。 | 請參閱擴充 API 驅動的佈建以同步處理自訂屬性的教學課程 |
| 6. | 您希望將資料從記錄系統自動上傳至輸入佈建 API 端點。 | 請參閱教學課程 * PowerShell 快速入門 * Azure Logic Apps 快速入門 |
| 7. | 您希望針對輸入佈建 API 問題進行疑難排解 | Refer to the Troubleshooting guide. |
外部學習資源
我們的合作夥伴和 Microsoft MVP 所建立的下列內容，提供如何部署和設定各種整合案例的 API 驅動佈建的額外指導。
Video tutorials
- 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 範本