API 驅動入站佈建的常見問題

本文回答有關 API 支持的入站配置的常見問題 (FAQ)。

新的入口佈建 /bulkUpload API 與 MS Graph 使用者 API 有何不同？

布建 /bulkUpload API 與 MS Graph 使用者 API 端點之間有顯著差異。

• 承載格式：MS Graph 使用者 API 端點需要 OData 格式的數據。 新入站佈建 /bulkUpload API 的請求負載格式會採用 SCIM 架構構造。 叫用此 API 時，請將 'Content-Type' 標頭設定為 application/scim+json。
• 工作結束結果：
  • 當身分識別數據傳送至 MS Graph 使用者 API 端點時，會立即處理，並在 Microsoft Entra 使用者設定檔上執行建立/更新/刪除作業。
  • Microsoft Entra 布建服務會以非同步方式處理傳送至布建/bulkUpload API 的請求資料。 布建作業會套用IT系統管理員所設定的範圍規則、屬性對應和轉換。這會在 Microsoft Entra 使用者設定檔或內部部署 AD 使用者配置檔上起始 Create/Update/Delete 作業。
• IT 系統管理員會保留控制權：使用 API 驅動的輸入布建，IT 系統管理員可以更充分掌控傳入身分識別數據的處理方式，並對應至Microsoft Entra 屬性。 他們可以定義範圍規則，以排除特定類型的身分識別數據（例如，承包商數據），並使用轉換函式在使用者配置檔上設定屬性值之前衍生新的值。

輸入布建 /bulkUpload API 是否為標準 SCIM 端點？

MS Graph 輸入布建 /bulkUpload API 會在要求承載中使用 SCIM 架構，但它 不是 標準化的 SCIM API 端點。 這就是為什麼。

一般而言，SCIM 服務端點會處理具有 SCIM 承載的 HTTP 要求 （POST、PUT、GET），並將其轉譯為身分識別存放區上的個別作業（建立、更新、查閱）。 SCIM 服務端點將指定操作語義（例如建立、更新或刪除身分識別）的責任放在 SCIM API 客戶端上。 適用於 API 用戶端確知其應在身分識別存放區中的使用者執行哪些操作的情境，此機制運作良好。

MS Graph 匯入設置 /bulkUpload 的設計旨在處理由三個獨特需求所塑造的不同企業身份整合的案例。

1. 能夠以異步方式大量處理記錄（例如，處理 50K+ 筆記錄）
2. 能夠在資料載荷中包含任何身分識別屬性（例如成本中心、薪資等級、識別證號）
3. 支援對作業語意不太了解的 API 用戶端。 這些用戶端是非 SCIM API 用戶端，具有原始源數據的存取權（例如，CSV 檔案、SQL 資料表或 HR 記錄中的記錄）。 這些客戶端沒有處理能力來讀取每個記錄，也無法判斷在身分識別存放區上 Create/Update/Delete 的操作語義。

MS Graph 輸入布建 /bulkUpload API 的主要目標是讓客戶從 任何 身分識別數據源（例如 CSV/SQL/HR）傳送 任何 身分識別數據（例如 costCenter、付費等級、badgeId），以供Microsoft Entra 布建服務最終處理。 Microsoft Entra 布建服務會取用在此端點收到的大量承載數據、套用 IT 系統管理員所設定的屬性對應規則，並判斷數據承載是否會導致目標身分識別存放區中的 [建立]、[更新]、[啟用]、[停用] 作業（Microsoft Entra ID /內部部署 AD）。

佈建/bulkUpload API 是否支持內部部署的 Active Directory 網域作為目標？

是，佈建 API 支援以內部部署的 AD 網域為目標。

如何取得布建應用程式的 /bulkUpload API 端點？

/bulkUpload API 僅適用於以下類型的應用程式：「API 驅動的輸入布建至 Microsoft Entra ID」和「API 驅動的輸入布建至內部部署 Active Directory」。 您可以從 [布建] 刀鋒視窗首頁擷取每個布建應用程式的唯一 API 端點。 在 [>檢視技術資訊，複製 [布建 API 端點 URL]。

格式如下：

https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload

如何使用布建 /bulkUpload API 執行完整同步處理？

若要執行完整同步處理，請使用您的 API 用戶端，以大量要求將所有使用者的數據從信任的來源傳送至 API 端點。 將所有數據傳送至 API 端點之後，下一個同步處理週期會處理所有用戶記錄，並可讓您使用布建記錄 API 端點來追蹤進度。

如何使用配置 /bulkUpload API 執行增量同步？

若要執行差異同步處理，請使用您的 API 用戶端，只傳送受信任來源中資料已變更的使用者的相關資訊。 將所有數據傳送至 API 端點之後，下一個同步處理週期會處理所有用戶記錄，並可讓您使用布建記錄 API 端點來追蹤進度。

重新啟動布建如何運作？

只有在需要時才使用 [重新啟動布建 ] 選項。 以下是其運作方式：

案例 1： 當您按兩下 [ 重新啟動布建 ] 按鈕，且作業目前正在執行時，作業會繼續處理已暫存的現有數據。 重新啟動布建作業不會中斷現有的迴圈。 在後續的循環中，布建服務會清除所有委付，並選擇新的大量請求進行處理。

案例 2： 當您按兩下 [ 重新啟動布建 ] 按鈕且作業 未 執行時，則在執行後續迴圈之前，布建引擎會清除在重新啟動前上傳的數據、清除任何委付，並且只會處理新的傳入數據。

如何使用布建 /bulkUpload API 端點建立使用者？

以下是與 /bulkUpload API 端點相關聯的布建作業如何處理傳入的用戶承載：

1. 作業會擷取布建作業的屬性對應，並記下相對應的屬性對（預設情況下，API 屬性 externalId 用於與 Microsoft Entra ID 中的 employeeId 進行匹配）。
2. 您可以變更這個預設屬性配對。
3. 作業會擷取大量要求承載中的每個作業。
4. 作業會檢查要求中的值比對標識碼（預設為 屬性 externalId），並使用它來檢查Microsoft Entra ID 中是否有具有相符 employeeId 值的使用者。
5. 如果作業找不到相符的使用者，則作業會套用同步處理規則，並在目標目錄中建立新的使用者。

若要確保在 Microsoft Entra ID 中建立正確的使用者，請在對應中定義正確的比對屬性對，以便在來源和 Microsoft Entra ID 中唯一識別使用者。

我們如何為 UPN 產生唯一的值？

布建服務無法檢查重複的userPrincipalName （UPN）並處理衝突。 如果UPN屬性的預設同步處理規則會產生現有的UPN值，則使用者建立作業會失敗。

以下是一些您可以考慮用來產生唯一 UPN 的選項：

1. 在 API 用戶端中新增唯一 UPN 產生邏輯。
2. 更新 UPN 屬性的同步處理規則以使用 RandomString 函式，並將套用對應參數設定為 On object creation only。 範例：

Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

3. 如果您要佈建至內部部署 Active Directory，您可以使用 SelectUniqueValue 函式，並將套用對應參數設定為 On object creation only。

我們如何將更多 HR 屬性傳送至布建 /bulkUpload API 端點？

根據預設，API 端點支援處理屬於 SCIM 核心使用者和企業用戶架構的任何屬性。 如果您想要傳送更多屬性，您可以擴充布建應用程式架構、將新屬性對應至Microsoft Entra 屬性，並更新大量要求以傳送這些屬性。 請參閱 擴充 API 驅動布建以同步處理自訂屬性的教學課程。

我們如何從布建流程中排除特定使用者？

您可能有一個案例，您想要將所有用戶傳送至 API 端點，但只包含布建流程中的特定使用者，並排除其餘的使用者。

您可以使用 範圍篩選來達成此目的。 在配置應用程式設定時，您可以定義來源物件範圍，並使用「包含規則」（例如，僅處理部門為 EQUALS Sales 的使用者）或「排除規則」（例如，排除部門不是 Sales 的使用者）來排除特定的使用者。

請參閱 將使用者或群組限定於範圍篩選條件進行布建。

如何使用布建 /bulkUpload API 端點來更新使用者？

以下是與 /bulkUpload API 端點相關聯的布建作業如何處理傳入的用戶承載：

1. 布建作業會擷取布建作業的屬性對應，並記錄相符的屬性對（預設情況下，使用 externalId API 屬性與 Microsoft Entra ID 中的 employeeId 匹配）。 您可以變更這個預設屬性配對。
2. 任務會從批次請求負載中提取操作。
3. 作業會檢查 SCIM 要求中的值比對標識碼（預設為：API 屬性 externalId），並使用它來檢查Microsoft Entra ID 中是否有相符 employeeId 值的使用者。
4. 如果作業找到相符的使用者，則會套用同步處理規則，並比較來源和目標配置檔。
5. 如果作業判斷某些值已變更，則會更新目錄中對應的用戶記錄。

若要確保正確的使用者會在 Microsoft Entra ID 中更新，請務必在您的映射中定義正確的配對屬性組，以唯一識別您來源和 Microsoft Entra ID 中的使用者。

我們可以建立多個支援 API 驅動輸入配置的應用程式嗎？

是，您可以。 以下是一些可能需要多個布建應用程式的案例：

案例 1： 假設您有三個受信任的數據源：一個用於員工，一個用於承包商，另一個用於廠商。 您可以建立三個獨立的佈建應用程式—每一個身分識別類型都有其專屬的屬性對應。 每個布建應用程式都有唯一的 API 端點，您可以將個別的承載傳送至每個端點。

您可以從 [配置] 面板首頁擷取每個作業的唯一 API 端點。 前往 統計數據至今>檢視技術資訊，然後複製 布建 API 端點 URL。

案例 2： 假設您有多個真實來源，每個來源都有自己的屬性集。 例如，HR 提供作業資訊屬性（例如 jobTitle、employeeType），而 Badging 系統則提供徽章資訊屬性（例如 badgeId ，使用擴充屬性來表示）。 在此案例中，您可以設定兩個布建應用程式：

• 布建應用程式 #1 ，可從您的 HR 來源接收屬性並建立使用者。

• 布建應用程式 #2 ，接收來自 Badging 系統的屬性，並且只會更新用戶屬性。 此應用程式中的屬性對應僅限於徽章資訊屬性，且在 [目標物件動作] 中僅允許啟用更新。

• 這兩個應用程式使用相同的相符識別碼群組 （externalId<->employeeId）

如何使用 /bulkUpload API 端點來處理終止？

若要處理終止程序，請識別來源中的屬性以在 Microsoft Entra ID 中設定 accountEnabled 旗標。 如果您要布建至內部部署 Active Directory，請將該來源屬性對應至 accountDisabled 屬性。

根據預設，與 SCIM Core 使用者架構屬性 active 相關聯的值會決定目標目錄中用戶帳戶的狀態。

如果屬性設定為 true，預設對應規則會啟用帳戶。 如果屬性設定為 false，則預設對應規則會停用帳戶。

如何防止意外停用/刪除使用者？

若要防止和復原意外刪除，建議您在布建應用程式中 設定意外刪除閾值 ，並 啟用內部部署 Active Directory 回收站。 在布建應用程式的 [屬性對應 ] 刀鋒視窗中，在 [ 目標物件動作 ] 下停用 [刪除 ] 作業。

復原已刪除的帳戶

• 如果作業的目標目錄是 Microsoft Entra ID，則會軟刪除相符的使用者。 您可以在 Microsoft Entra 系統管理中心的 [已刪除的使用者 ] 頁面上看到該使用者接下來 30 天，而且可以在該時間還原。
• 如果作業的目標目錄是內部部署 Active Directory，則會硬式刪除相符的使用者。 如果已啟用 Active Directory 回收站 ，您可以還原已刪除的內部部署 AD 用戶物件。

我們需要於每一個請求中從 HR 系統傳送所有使用者嗎？

否，您不需要在每次要求中從 HR 系統傳送所有使用者或「單一事實來源」的資料。 只要傳送您想要建立或更新的使用者即可。

API 是否支援所有 HTTP 動作 （GET/POST/PUT/PATCH）？

否，/bulkUpload 布建 API 端點僅支援 POST HTTP 動作。

如果我想要更新使用者，是否需要傳送 PUT/PATCH 要求？

否，API 端點不支援 PUT/PATCH 要求。 若要更新使用者，請在POST大量要求承載中傳送與使用者相關聯的數據。

處理 API 端點所接收數據的配置作業，會根據設定的同步規則，自動偵測在 POST 請求有效負載中接收到的用戶是否需要被建立、更新、啟用或停用。 身為 API 用戶端，如果您想要更新使用者配置檔，就不需要再採取任何步驟。

如何支援回寫？

目前的 API 僅支援輸入數據。 這裡有一些選項可供考慮，以實作將 Microsoft Entra ID 產生的屬性（如電子郵件、使用者名稱、電話）回寫至 HR 系統的方案：

• 選項 1 – SCIM 連線至 HR 端點/代理服務，以更新 HR 資料來源

  • 如果記錄系統提供 SCIM 端點以進行使用者更新，您可以在企業應用程式集錦中建立自定義 SCIM 應用程式，並依照文件中的指示設定布建。
  • 如果記錄系統未提供 SCIM 端點，請探索設定 Proxy SCIM 服務的可能性，該服務會接收更新並將變更傳播至 HR 系統。

• 選項 2 – 針對回寫案例使用Microsoft Entra ECMA 連接器

  • 根據客戶需求，探索是否可以使用其中一個 ECMA 連接器（PowerShell/ SQL / Web Services）。

• 選項 3 – 在聯結器工作流程中使用生命週期工作流程自定義擴充工作

  • 在生命週期工作流程中，定義 Joiner 工作流程，並定義會 叫用 Logic Apps 程式的自訂擴充工作，以更新 HR 系統或產生 HR 系統取用的 CSV 檔案。

後續步驟

• 設定由 API 驅動的入站佈建應用程式
• 若要深入瞭解 API 驅動輸入布建，請參閱 輸入使用者布建 API 概念。