簡介
本文件涵蓋輸入佈建 API 的常見錯誤和問題，以及如何進行疑難排解。
疑難排解案例
無效的資料格式
問題描述
- 您收到錯誤訊息
Invalid Data Format，HTTP 回應碼為 400（錯誤的要求）。
可能的原因
- 您會根據佈建 /bulkUpload API 規格傳送有效的大量要求，但尚未將 HTTP 要求標頭「Content-Type」設定為
application/scim+json。 - 您傳送的批次請求不符合佈建 /bulkUpload API 規格。
解決方法：
- 確定 HTTP 要求已將
Content-Type標頭設定為值application/scim+json。 - 請確保大量請求酬載符合佈建 /bulkUpload API 規格。
佈建記錄中沒有任何記錄
問題描述
- 您已將要求傳送至佈建 /bulkUpload API 端點，而且您收到 HTTP 202 回應碼，但佈建記錄中沒有對應至要求的資料。
可能的原因
- 您的 API 驅動佈建應用程式已暫停。
- 佈建服務尚未將大量要求處理的詳細資料更新至佈建記錄檔中。
- 您的內部部署布建代理程式狀態為非使用中（如果您正在執行 /使用 API 導向的內部使用者布建至內部部署 Active Directory）。
解決方法：
- 確認您的佈建應用程式正在執行。 如果未執行，請選取功能表選項 開始佈建 來處理資料。
- 重新啟動內部部署代理程式，將內部部署佈建代理程式狀態變更為使用中。
- 在處理要求和寫入布建記錄之間，預期會有 5 分鐘到 10 分鐘的延遲。 如果您的 API 用戶端將資料傳送至佈建 /bulkUpload API 端點，則會導致要求調用和佈建記錄查詢之間出現時間延遲。
禁止 403 回應碼
問題描述
- 您已將要求傳送至佈建 /bulkUpload API 端點，並取得 HTTP 403（禁止）回應碼。
可能的原因
- 圖形許可權
SynchronizationData-User.Upload未指派給您的 API 用戶端。
解決方法：
- 將 Graph 權限
SynchronizationData-User.Upload指派給 API 用戶端，然後重試作業。
請求過多 429 回應碼
bulkUpload API 端點會強制執行下列節流限制，並在違反這些限制時傳回 429 回應碼。
每 5 秒 40 個 API 呼叫 – 如果呼叫次數在 5 秒範圍內超出此限制，則用戶端會收到 429 回應。 避免這種情況的一種方法是使用客戶端要求提交邏輯中的延遲，以調整提交請求的速度。
在 24 小時內 6,000 個 API 呼叫 – 如果呼叫數目超過此限制，則用戶端會取得 429 個回應。 避免這種情況的一種方法是確保您的 SCIM 大量承載已最佳化，以針對每個 API 呼叫使用最多 50 筆記錄。 使用此方法，您可以每隔 24 小時傳送 300K 筆記錄。
儲存桶已滿 500 回應碼
問題描述
- SCIM 用戶端會收到 HTTP 500（內部伺服器錯誤）訊息：「儲存已接收資料的桶已滿，請等待同步服務處理已接收資料並重試此請求。」
- 當大量人力資源資料集傳送到配置
/bulkUpload端點時，你可能會在初始同步或全同步週期中看到這個錯誤。
發生此錯誤的原因
- 「bucket」是佈建服務用來在處理前緩衝傳入
/bulkUpload酬載的暫時接收佇列。 - 每個 API 驅動的配置工作都有專屬的擷取佇列。
- 佈建服務會持續處理佇列中的承載資料，然後刪除已處理的資料。 如果這個處理後刪除的循環跟不上或停止運作，佇列中的資料可能會不斷累積，直到儲存桶被裝滿。
可能原因與解決
| 原因 | Resolution |
|---|---|
| 承載資料處理失敗，原因是對應不正確（例如，嘗試更新由內部部署 Active Directory 管理的 Microsoft Entra ID 屬性）或資料無效。 失敗的有效載荷仍留在隊列中，最終可填滿桶。 | 檢視配置日誌以識別失敗的請求處理，修正映射或資料問題，重新啟動配置工作，並重新傳送請求。 |
| API 驅動的配置工作處於 暫停 或 停止 狀態。 請求會持續進入佇列，但處理程序不會執行。 | 恢復佈建工作，讓它能處理並清空佇列中的請求。 |
| API 驅動的配置工作長時間處於 隔離 狀態。 請求會持續進入佇列，但處理程序未執行。 | 重新啟動佈建作業以解除隔離。 重新啟動時，已排隊的資料會被清除，這可能需要時間。 等大約 40 分鐘，然後重新發送 SCIM /bulkUpload 請求。 |
| 來源系統傳送 SCIM 資料的速度比配置工作處理的速度還快。 | Pace 請求提交。 每次批量上傳後，請檢查 HTTP 狀態碼。 如果收到 HTTP 500 錯誤並顯示儲存貯體已滿訊息，請先暫停用戶端（例如 5 到 10 分鐘），再重試。 |
未經授權的 401 回應碼
問題描述
- 您已將要求傳送至佈建 /bulkUpload API 端點，並取得 HTTP 401（未經授權）回應碼。 錯誤碼會顯示「InvalidAuthenticationToken」，並顯示「存取權杖已過期或尚未有效」的訊息。
可能的原因
- 您的存取權杖已到期。
解決方法：
- 為您的 API 用戶端產生新的存取權杖。
作業進入隔離狀態
問題描述
- 您剛啟動佈建應用程式，而該應用程式目前處於隔離狀態。
可能的原因
- 在開始工作之前，您尚未設定通知電子郵件。
解析： 移至 [編輯佈建] 功能表項目。 在 「設定」 底下，「發生失敗時傳送電子郵件通知」 旁邊有一個複選框，以及一個用於輸入 「通知電子郵件」 的欄位。 請務必勾選方塊、提供電子郵件，並儲存變更。 按 重新啟動佈建 以將工作從隔離區中取出。
建立使用者 - 無效的 UPN
問題描述 使用者佈建失敗。 佈建記錄會顯示錯誤碼：AzureActiveDirectoryInvalidUserPrincipalName。
解決方法：
- 已進入 編輯屬性對應 頁面。
- 選取
UserPrincipalName對應，並將其更新為使用RandomString函式。 - 複製此運算式並貼入運算式方塊中：
Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())
此運算式會將隨機數附加至 Microsoft Entra ID 所接受的 UPN 值，以修正此問題。
使用者建立失敗 - 無效網域
問題描述 使用者佈建失敗。 佈建記錄會顯示錯誤訊息，指出 domain does not exist。
解決方法：
- 移至 [編輯屬性對應] 頁面。
- 選取
UserPrincipalName對應，並將此運算式複製並貼到運算式輸入方塊中：Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())
此運算式會將預設網域附加至 Microsoft Entra ID 所接受的 UPN 值，以修正此問題。
已知限制：地址、電子郵件地址及電話號碼為多值欄位
問題描述
- API 驅動的佈建目前不會處理
addresses、emails和phoneNumbers中的 SCIM 多值屬性；當type值為home或任何其他非work的值時。 - 此限制適用於像
addresses[type eq "home"]、addresses[type eq "any-other-value"]、phoneNumbers[type eq "home"]和 這樣的表達式。
現況
- 只有
addresses[type eq "work"]，emails[type eq "work"]且phoneNumbers[type eq "work"]數值會被處理。
Workaround
- 當你需要 API 驅動的配置處理屬性時，請使用 該
work類型傳送支援的值。