了解常見的 User Sync Tool 錯誤及解決方法。
此頁面列出執行 User Sync Tool 時可能遇到的常見錯誤，以及解決每個錯誤的步驟。如需工具概覽以及設定、設置和指令參考的位置，請參閱 設定 User Sync Tool。
安裝和環境
當路徑超過 256 個字元時，這可能會在 Windows 上出現。建立名為 PEX_ROOT 的環境變數，值為 C:\pex。如果您從 C: 以外的磁碟機執行指令碼，請變更磁碟機代號以符合實際情況。有時需要重新啟動系統才能使變更生效。
從 user-sync.pex 所在的資料夾內執行 python 命令列。
- 檢查您系統上安裝的 Python 版本是否為 32 位元。解除安裝 32 位元版本並安裝 64 位元版本。
- 檢查您從 GitHub 下載的 user-sync.pex 版本是否與您的 Python 版本和作業系統相符。例如，針對 Windows 64 位元和 Python 3，請下載 user-sync-v2.3-win64-py365.zip。使用建置 .pex 時所用的 Python 版本，而非最新的 Python。.zip 的尾碼識別版本：對於 user-sync-v2.3-win64-py365.zip，即為 Python 3.6.5。
此錯誤記錄在使用 User Sync Tool v2.3 和 Python 3.7.0 的 macOS High Sierra 上。在終端機中執行 brew install openssl 可解決該情況。
連線、逾時和流量控制
如果逾時時間少於 30 分鐘，當達到一分鐘內允許的 API 呼叫配額時，會出現這些警告。此工具使用指數後退機制進行重試，增加重試之間的時間，並在三次失敗嘗試後停止。讓指令碼執行到完成。
如果逾時超過 1000 秒，節流與每個 User Sync Tool 實例的執行頻率有關。執行個體如果執行過於頻繁，會被節流 30 至 75 分鐘。逾時僅會暫停工具一段時間；之後工具會恢復並繼續同步。
由於工具會偵測兩個執行個體同時啟動的情況，在第一個執行個體完成之前，不會執行新的執行個體。在此情況下，記錄可能會顯示處理程序正在進行的訊息。
為獲得最佳效能，請遵循下列執行頻率建議：
- 將排程工作設定為至少間隔 2 小時重複執行。
- 設定排程工作觸發程序，避免在 :00 或 :30 分鐘時啟動，以免遇到尖峰流量。
- 如果您必須更頻繁地執行工具，請考慮使用推播策略 (變更差異) 而不是完整同步。
- 讓工具的執行排程符合您組織的工作日。例如，如果您的組織夜間不需要修改佈建設定，就不要在夜間執行同步作業。
工具無法連線至公用 API 端點。本機設定 (如防火牆規則、代理伺服器封鎖流量或帳戶網際網路存取權設定) 可能會阻止存取權。新增 https_proxy 環境變數，其值為 http://<proxyAddress>:<port> 或 https://<proxyAddress>:<port> 等，或許有助於解決此問題。在其他情況下，請允許存取這些端點：ims-na1.adobelogin.com:443 和 usermanagement.adobe.io:443。只能透過清除執行帳戶對這些端點的存取權來進行本機解決。
本機代理伺服器上的 SSL 檢查會造成此問題。
解決方案 1：以 PEM 格式取得代理伺服器的根 CA 憑證 (例如 thecert.crt)。如果是 DER 格式，請使用以下 openssl 指令轉換為 PEM：openssl x509 -inform DER -in thecert.crt -out thecert.pem -outform PEM。PEM 檔案會在 -----BEGIN CERTIFICATE----- 和 -----END CERTIFICATE----- 行之間顯示 base64 編碼字串。建立名為 REQUESTS_CA_BUNDLE 的環境變數，並將其值設定為 thecert.pem 的路徑。
解決方案 2：在 Windows 上，如果工具從不同於作業系統和 Python 安裝磁碟的磁碟執行，可能會發生此錯誤。將整個指令碼移至作業系統所在的磁碟。如果這不可行，請將包含受信任根 CA 的 cacert.pem 檔案複製到其他磁碟，並將其路徑設定為 REQUESTS_CA_BUNDLE。如果代理伺服器也檢查 SSL 流量，請將代理伺服器根 CA 憑證內容複製到 cacert.pem 中，使代理伺服器憑證受到信任。預設的 Python 安裝會將憑證套件保存在 C:\Python36\Lib\site-packages\certifi\cacert.pem。
解決方案 3： 停用代理伺服器對 API 端點 ims-na1.adobelogin.com 和 usermanagement.adobe.io 的 SSL 檢查。
驗證與認證
umapi_api_key 的認證存放區項目可能遺失。在認證存放區中建立項目。請參閱使用者同步工具文件中關於在作業系統層級儲存認證的說明。
該值也可能已在認證存放區中新增到不同的使用者帳戶下，而目前連線的使用者缺少該項目。新增該項目，或切換使用者帳戶。
- 如果您無法快速識別問題，請重新產生金鑰對。
- 在 Windows 上執行指令碼時，請勿使用 umapi_private_key_data 屬性。請改為加密金鑰並將密碼儲存在認證管理員中。
- 如果您使用不同格式簽發金鑰對，請嘗試 RSA 256、2048 位元私密金鑰。
- 您可能已在 connector-umapi.yml 檔案中設定 secure_priv_key_pass_key: umapi_private_key_passphrase。確保認證存放區中相符的項目及其相關值保持一致。
在 Adobe Admin Console 中，前往「設定」，然後選擇「驗證設定」。可以選擇「對使用者最簡單 (密碼永不過期)」以外的選項。「更安全」或「最安全」選項可能會使連結到整合的技術帳戶密碼過期。若要修正此問題，請建立新的整合並在 connector-umapi.yml 檔案中更新中繼資料。已針對此問題部署修正程式，但它可能會影響 2018 年 10 月之前建立的整合。
- connector-umapi.yml 檔案中的 tech_acct 值可能與 Adobe Developer Console 中整合的技術帳戶 ID 不同。確認目前整合中的技術帳戶 ID，並將其複製到檔案中。
- 整合的公開憑證可能已到期。續約私用和公用金鑰、上傳公用金鑰，並以新的私用金鑰取代舊的私用金鑰。確認 connector-umapi.yml 檔案中的路徑指向正確的檔案。
- 確認整合是針對正確的組織。從 Adobe Developer Console 左上角的下拉式選單中選取組織，然後確認主要整合的技術帳戶 ID 以及其他中繼資料 (組織 ID、密碼和用戶端 ID)。
此錯誤出現在較舊的整合中。除了用於相同目的的現有整合之外，在 Adobe Developer Console 中建立新的整合 (或專案)。新的整合提供新的認證，因此請在 connector-umapi.yml 檔案中更新它們。金鑰配對 (私用和公用金鑰) 可能重新發行，因此新的私用金鑰必須取代現有的金鑰。
LDAP 和群組
- LDAP 中不存在使用該確切名稱的群組。新增群組的正確 LDAP 名稱。
- 在已宣告的 base_dn 下找不到該群組 (請參閱 connector-ldap.yml 檔案)。變更 base_dn 值以包含該群組。這主要發生在 base_dn 指向特定 OU 而非盡可能寬泛時。
輸出中的使用者群組 group_name 在 Adobe 端不存在。請建立它。如果您打算設定產品授權設定 (PLC) 的名稱而非使用者群組，請參閱 User Sync Tool 說明文件中關於 在企業目錄中建立對應群組 的內容。
感興趣的群組可能在子網域中，而 host 值是其中一個根網域。將 主機 值變更為可找到使用者群組的子網域。如果使用者或群組同時在根網域及其子網域中，請在根網域上使用全域目錄連接埠，並將子網域群組變更為 Universal 而非 Global。使用全域目錄的主機值範例：ldap://domain.local:3268 或 ldaps://domain.local:3269。使用全域目錄連接埠時，將 base_dn 設定為空值：base_dn: ""。
使用者和帳戶建立
用於建立帳戶的網域可能未在您的組織中聲明或受信任。在 Adobe Admin Console 的「設定」下，活躍網域會顯示綠色標幟或圓點。如果沒有顯示，完成網域聲明程序可以解決此問題。
嘗試建立 Federated ID 帳戶，但目錄是為 Enterprise ID 建立的，或反之。在 user-sync-config.yml 檔案中尋找 user_identity_type 屬性。將值設定為符合 Adobe Admin Console 中顯示的目錄類型 (設定，然後身分識別，然後網域，然後該網域的目錄類型值)。
有時 @claimed-domain.com 網域屬於另一個組織，該組織設定了 Azure 或 Google 連接器來同步帳戶到 Admin Console，然後該網域受信任於使用使用者同步工具來同步 @claimed-domain.com 格式帳戶的不同組織。當工具從 LDAP 伺服器提取 user@claimed-domain.com 帳戶以在次要組織中建立時，會出現此訊息，但該帳戶尚未在主要組織中透過 Azure 或 Google 連接器建立或同步。在使用 Azure 或 Google 連接器的組織中建立或同步 user@claimed-domain.com 帳戶，然後在受託組織中使用使用者同步工具重新嘗試同步。
此一般錯誤有多種原因，但常見問題是建立動作中使用的網域處於 Azure 或 Google 同步設定下。若要檢查，請使用系統管理員帳戶登入 Adobe Admin Console，前往設定，選取包含該網域的目錄，然後選取同步標籤。如果出現同步來源卡片，修正方式取決於應如何繼續同步：
- 如果 Azure 或 Google 連接器應執行同步，請繼續設定同步來源並完全移除使用者同步工具。
- 如果使用者同步工具應執行同步，請選取「前往設定」，然後選取頁面底部的「移除同步」。接著工具會照常執行。
如果沒有出現同步來源卡片，目前的工具可能針對網域受託於不同 Console (擁有組織) 的 Console 執行。該組織可能已開啟 Azure 或 Google 同步，這會造成此錯誤。先在擁有的 Console 中同步帳戶，然後使用工具在目前的 Console 中建立帳戶。
如果這些都不符合，請聯絡企業支援。
