共用方式為

輸入佈建 API 問題疑難排解

  • 發行項

簡介

本文件涵蓋輸入佈建 API 的常見錯誤和問題，以及如何進行疑難排解。

疑難排解案例

無效的資料格式

問題描述

  • 您收到有 HTTP 400 (不正確的要求) 回應碼的錯誤訊息 Invalid Data Format。

可能的原因

  1. 您會根據佈建 /bulkUpload API 規格傳送有效的大量要求，但尚未將 HTTP 要求標頭「Content-Type」設定為 application/scim+json。
  2. 您傳送不符合佈建 /bulkUpload API 規格的大量要求。

解決方法：

  1. 確定 HTTP 要求已將 Content-Type 標頭設定為值 application/scim+json。
  2. 請確定大量要求承載符合佈建 /bulkUpload API 規格。

佈建記錄中沒有任何內容

問題描述

  • 您已將要求傳送至佈建 /bulkUpload API 端點，而且您收到 HTTP 202 回應碼，但佈建記錄中沒有對應至要求的資料。

可能的原因

  1. 您的 API 驅動佈建應用程式已暫停。
  2. 佈建服務尚未使用大量要求處理詳細資料來更新佈建記錄。
  3. 您的內部部署佈建代理程式狀態為非使用中狀態 (如果您執行 /API 驗動的輸入使用者佈建至內部部署 Active Directory)。

解決方法：

  1. 確認您的佈建應用程式正在執行。 如果未執行，請選取功能表選項 開始佈建 來處理資料。
  2. 重新啟動內部部署代理程式，將您的內部部署佈建代理程式狀態開啟為作用中。
  3. 在處理要求和寫入佈建記錄之間，預期會有 5 到 10 分鐘的延遲。 如果您的 API 用戶端將資料傳送至佈建 /bulkUpload API 端點，則會導致要求調用和佈建記錄查詢之間出現時間延遲。

禁止 403 回應碼

問題描述

  • 您已將要求傳送至佈建 /bulkUpload API 端點，並取得 HTTP 403（禁止）回應碼。

可能的原因

  • Graph 權限 SynchronizationData-User.Upload 未指派給您的 API 用戶端。

解決方法：

  • 將 Graph 權限 SynchronizationData-User.Upload 指派給 API 用戶端，然後重試作業。

要求太多 429 回應碼

bulkUpload API 端點會強制執行下列節流限制，並在違反這些限制時傳回 429 回應碼。

  • 每 5 秒 40 個 API 呼叫 – 如果呼叫次數在 5 秒範圍內超出此限制，則用戶端會收到 429 回應。 避免這種情況的一種方法是使用客戶端要求提交邏輯中的延遲，以調整提交請求的速度。 

  • 24 小時內 6000 個 API 呼叫 – 如果呼叫次數超出此限制，則用戶端會收到 429 回應。 避免這種情況的一種方法是確保您的 SCIM 大量承載已最佳化，以針對每個 API 呼叫使用最多 50 筆記錄。 使用此方法，您可以每隔 24 小時傳送 300K 筆記錄。

未經授權的 401 回應碼

問題描述

  • 您已將要求傳送至佈建 /bulkUpload API 端點，並取得 HTTP 401（未經授權）回應碼。 錯誤碼會顯示「InvalidAuthenticationToken」，並顯示「存取權杖已過期或尚未有效」的訊息。

可能的原因

  • 您的存取權杖已到期。

解決方法：

  • 為您的 API 用戶端產生新的存取權杖。

工作進入隔離狀態

問題描述

  • 您剛開始佈建應用程式，且處於隔離狀態。

可能的原因

  • 在開始工作之前，您尚未設定通知電子郵件。

解析： 移至 [編輯佈建] 功能表項目。 在 「設定」 底下，「發生失敗時傳送電子郵件通知」 旁邊有一個複選框，以及一個用於輸入 「通知電子郵件」 的欄位。 請務必勾選方塊、提供電子郵件，並儲存變更。 按一下 [重新啟動佈建] ，讓工作無法隔離。

使用者建立 - 無效的 UPN

問題描述 使用者佈建失敗。 佈建記錄會顯示錯誤碼：AzureActiveDirectoryInvalidUserPrincipalName。

解決方法：

  1. 移至 [編輯屬性對應] 頁面。
  2. 選取 UserPrincipalName 對應，並將其更新為使用 RandomString 函式。
  3. 複製此運算式並貼入運算式方塊中：Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

此運算式會將隨機數附加至 Microsoft Entra ID 所接受的 UPN 值，以修正此問題。

使用者建立失敗 - 無效網域

問題描述 使用者佈建失敗。 佈建記錄會顯示錯誤訊息，指出 domain does not exist。

解決方法：

  1. 移至 [編輯屬性對應] 頁面。
  2. 選取 UserPrincipalName 對應，並將此運算式複製並貼到運算式輸入方塊中：Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

此運算式會將預設網域附加至 Microsoft Entra ID 所接受的 UPN 值，以修正此問題。

下一步