分享方式：

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. 能夠在承載中包含任何身分識別屬性 (例如 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)，而門禁系統則提供門禁卡資訊屬性 (例如 badgeId，使用分機屬性來表示)。 在此案例中，您可以設定兩個佈建應用程式：

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

  • 佈建應用程式 #2，可接收來自門禁系統的屬性，並且只會更新使用者屬性。 此應用程式中的屬性對應僅限於門禁卡資訊屬性，且僅啟用 [目標物件動作] 底下的更新。

  • 這兩個應用程式使用相同的比對識別碼配對 (externalId<->employeeId)

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

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

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

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

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

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

復原已刪除的帳戶

  • 如果作業的目標目錄是 Microsoft Entra ID，則會虛刪除相符的使用者。 接下來 30 天內，您可以在 Microsoft Entra 系統管理中心 [已刪除的使用者] 頁面看到該使用者，並且可在該時間還原。
  • 如果作業的目標目錄是內部部署 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：在加入者工作流程中使用生命週期工作流程自訂擴充作業

下一步