共用方式為

API 驅動輸入布建的常見問題

  • 發行項

本文回答 API 驅動輸入布建的常見問題（常見問題）。

新的輸入布建 /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用戶端上放置指定作業語意的 onus，是否要建立/更新/刪除身分識別。 此機制適用於 API 用戶端知道它想要針對身分識別存放區中使用者執行的作業。

MS Graph 輸入布建 /bulkUpload 的設計訴求是處理由三個獨特需求所塑造的不同企業身分識別整合案例：

  1. 能夠以異步方式大量處理記錄（例如，處理 50K+ 筆記錄）
  2. 能夠在承載中包含任何身分識別屬性（例如 costCenter、付費等級、badgeId）
  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. 作業會擷取布建作業的屬性對應，並記下相符的屬性組（根據預設 externalId ，API 屬性是用來與 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())

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

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

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

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

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

您可以使用範圍篩選來達成此目的。 在布建應用程式組態中，您可以定義來源物件範圍，並排除特定使用者使用「包含規則」來處理（例如，只有處理部門 EQUALS Sales 的使用者）或「排除規則」（例如，排除屬於 Sales 的使用者、部門 NOT EQUALS 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 端點/Proxy 服務，進而更新 HR 來源

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

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

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

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

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

下一步