適用於企業。
列示執行 UST 時的部分常見錯誤和解決錯誤的相關提示
主控台錯誤輸出範例：
FileNotFoundError: [Errno 2] 找不到檔案或目錄：'C:\\Users\\USER\\.pex\\install\\pycryptodome [...]'
可能會顯示在 Windows 上，因為路徑多於 256 個字元。
提示：建立名為 PEX_ROOT 的環境變數，且具備 C:\pex 值 (如果從 C: 磁碟機執行指令碼，或變更字母使其相符)。 有時必須重新啟動系統才能使其生效。
錯誤輸出範例：
python：無法開啟檔案 'user-sync.pex'：[Errno 2] 找不到檔案或目錄
提示：務必在 user-sync.pex 所在資料夾內執行 python 命令列。
記錄錯誤輸出範例：
2018-01-01 11:49:42 28102 警告 umapi - UMAPI 逾時...服務無法使用 (第 1 次嘗試時出現代碼 429) 2018-01-01 11:49:42 28102 警告 umapi - 42 秒後重試...
秘訣：如果逾時時間少於 30 分鐘，當一分鐘內的 API 呼叫配額已達上限時，就會收到這些警告訊息。 UST 具備可再次呼叫的指數輪詢機制，延長重試間的時間。 指令碼會在嘗試失敗三次後停止。
這裡的建議是讓指令碼執行到最後。
如果逾時時間超過 1000 秒，這將是與每個使用者同步工具執行個體的執行頻率相關的限制。如果觀察到某個執行個體執行頻率更高，則會在 30 到 75 分鐘之間受到限制。雖然逾時只會讓 UST 暫停一段時間 (所以不是關鍵性的停止錯誤)，但 UST 會知道在之後恢復並繼續同步。
由於指令碼能識別同時啟動兩個執行個體的情況，因此在初始執行個體完成執行之前，無法觸發新的執行個體。在這種情況下，UST 記錄中可能會出現一條錯誤訊息，提到「程序已在進行中」。
以下是一些關於執行頻率的最佳效能建議：
記錄項目範例：
2018-01-01 11:49:42 28102 錯誤 umapi.action - 請求 ID 中的錯誤：action_1 (使用者：{'user': 'myuser@domain2.com', 'requestID':'action_1'}，指令：{'createFederatedID': {'email': 'myuser@domain2.com', 'country': 'US', 'option': 'ignoreIfAlreadyExists', 'firstname': 'fname', 'lastname': 'lname'}})：代碼："error.user.belongs_to_another_org" 訊息："不允許邀請來自其他組織擁有的驗證來源的使用者"
提示：建立帳戶所使用的網域可能不是您組織所宣告擁有/信任的網域。「Admin Console -> 設定」中，使用中的網域應會顯示綠色旗標或點。若未顯示，完成網域宣告程序即可解決此問題。
記錄項目範例：
2018-01-01 12:34:23 13383 錯誤 umapi.action - 請求 ID 中的錯誤：action_6 (使用者：{'user': 'user@domain.com', 'requestID': 'action_6'}，指令：{'createEnterpriseID': {'email': 'user@domain.com', 'option': 'updateIfAlreadyExists', 'firstname': 'test', 'lastname': 'user', 'country': 'US'}})：代碼："error.user.type_mismatch" 訊息："邀請所要求的使用者類型與宣稱的網域類型不符"
主控台錯誤輸出範例：
無法執行 PEX 檔案，缺少相容的相依項目： pyyaml cryptography cffi umapi-client pycryptodome pyldap psutil user-sync
秘訣：
a) 確認系統上安裝的 Python 版本是否為 32 位元版本。 解除安裝 32 位元版本並安裝 64 位元版本，以修正此問題。
b) 確認從 GitHub 下載的 user-sync.pex 版本是否符合您的 Python 版本和作業系統類型。 例如，對於 Windows 64 位元和 Python 3，需要下載 user-sync-v2.3-win64-py365.zip。
使用最新 Python 版本不一定就是好辦法。 不妨試著比對 Python 版本 (最初建立的 .pex)。 依照所下載 .zip 檔案的尾碼，分辨適合的 Python 版本。 舉上方範例為例 (user-sync-v2.3-win64-py365.zip)，可知該範例適合使用 Python 3.6.5。
記錄項目範例：
2018-01-01 09:52:23 7920 偵錯 umapi - umapi：從檔案 C:\path\to\private.key 讀取私密金鑰資料 2018-01-01 09:52:23 7920 關鍵 main - umapi configuration.enterprise：解密私密金鑰時出錯，密碼錯誤或：不支援 RSA 金鑰格式
秘訣：
a) 如果無法快速識別問題，重新發行金鑰對會更快
b) 如果是在 Windows 中執行指令碼，請勿使用 umapi_private_key_data 屬性。 請改為將金鑰加密，並儲存「認證管理員」內的密碼。
c) 如果您使用其他格式發出金鑰對，請嘗試使用 RSA256 /2048 位元長度的私密金鑰
d) 您可能已在 connector-umapi.yml 檔案內設定 secure_priv_key_pass_key: umapi_private_key_passphrase。 在此情況下，請確認此認證的「認證存放區」中的項目與相關值相符 (請參閱下方)。
記錄項目範例：
2018-01-01 09:52:23 7920 關鍵 main - umapi 關鍵 main - umapi configuration.enterprise：安全儲存中沒有使用者 "someUUIDvalue@AdobeOrg" 的值，金鑰 "umapi_api_key"
秘訣：
a) umapi_api_key 的「認證存放區」項目可能遺失。 在「認證存放區」建立該項目。 如需說明文件，請參閱此處。
b) 可能是以其他使用者帳戶將該值新增至「認證存放區」， 但目前連結的使用者遺失此項目。 如有必要，請新增該項目或切換使用者帳戶。
錯誤輸出範例：
umapi_client.error.RequestError：請求錯誤 (401)：{"lastPage":false,"result":"error.internal.exceptionflys","message":"無法交換權杖"}
或
"umapi_client.error.RequestError：請求錯誤 (401)：{"lastPage":false,"result":"error.unauthorized","message":"無法驗證提供的權杖"}"
提示：或許您在「Admin Console -> 設定 -> 驗證設定」中，選擇了「對使用者而言最簡單」(密碼永不到期) 以外的選項。 如果啟用「更安全」或「最安全」選項，連結至整合項目的「技術帳戶」密碼可能會到期。
若要修正此問題，請建立新整合項目。 另外也務必更新 connector-umapi.yml 檔案中的中繼資料。
之前或許為其部署了修正，但 2018 年 10 月前建立的整合項目可能會受到影響。
錯誤輸出範例：
ConnectionError: HTTPSConnectionPool(host='usermanagement.adobe.io', port=443)：已超過與 url 的最大重試次數：/v2/usermanagement/users/someUUID@AdobeOrg/0?directOnly=True (由 NewConnectionError('<urllib3.connection.VerifiedHTTPSConnection object at 0x00000000027B9630>：無法建立新連線：[Errno 10061] 無法建立連線，因為目標電腦主動拒絕連線',) 所引起)
提示：
這與 UST 無法連結公用 API 端點有關。 本機設定可能因防火牆規則、代理封鎖流量、帳戶的網際網路存取設定等情形而存取受限。
在某些情況下，新增 https_proxy 環境變數並設定以下值可能會有所幫助：
http://<代理伺服器地址>:<連接埠> 或 https://<代理伺服器地址>:<連接埠>
其他情況下，允許系統存取下列端點可能會有幫助：
ims-na1.adobelogin.com:443
usermanagement.adobe.io:443
唯有為使用中的帳戶清除上述端點的存取權，才能在本機上解決此問題。
記錄項目範例：
2017-07-07 09:01:37 4916 關鍵 main - 連線到組織 [...] 的端點 https://usermanagement.adobe.io/v2/usermanagement 失敗：無法對 https://ims-na1.adobelogin.com/ims/exchange/jwt: 進行授權 回應代碼：400，回應文字：{"error_description":"JWT 中的元範圍不是綁定中元範圍的子集。","error":"invalid_scope"}
記錄項目範例 (偵錯模式)：
2017-07-07 09:01:37 4916 關鍵 main - UMAPI 連線到組織 ID 'someUUIDvalue@AdobeOrg' 失敗：無法對 https://ims-na1.adobelogin.com/ims/exchange/jwt: 進行授權
回應代碼：400，回應文字：{"error_description":"找不到組織和技術帳戶組合的有效綁定","error":"invalid_token"}
提示：
a) 這可能是因為 connector-umapi.yml 檔案中的 tech_acct 值與 https://developer.adobe.com/console/projects 中整合中的技術帳戶 ID 以外的值相對應。確認目前整合項目的技術帳戶 ID 值，並複製到此檔案。
b) 也可能是因為整合項目的公開憑證到期。 請先更新私人和公開金鑰。 接著，上傳公開金鑰，並以新的私人金鑰取代舊金鑰。 確認 connector-umapi.yml 檔案內的路徑，以指向正確檔案。
c) 確認是否為正確組織完成整合。 在 https://developer.adobe.com/console/projects 選取左上角下拉式清單中的「組織」。接著，確認該使用中整合項目的技術帳戶 ID 值，以及其他中繼資料 (組織 ID、密碼和用戶端 ID)。
記錄項目範例：
2017-07-07 09:01:37 4916 關鍵 main - UMAPI 連線到組織 ID 'someUUIDvalue@AdobeOrg' 失敗：[SSL: CERTIFICATE_VERIFY_FAILED] 憑證驗證失敗 (_ssl.c:661)
提示：這是由於本機代理伺服器啟用了 SSL 檢查導致的
解決方案1：取得代理的 PEM 格式的根 CA 證書（假設其名稱為 thecert.crt）。若是使用 DER 格式，請使用 openssl 命令將其轉換為 PEM：
openssl x509 -inform DER -in thecert.crt -out thecert.pem -outform PEM
注意：查看證書內容並看到
-----BEGIN CERTIFICATE----- 和 -----END CERTIFICATE----- 行之間的 base64 編碼字串，表示您擁有 PEM 格式的檔案。
接著，建立名為 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 檢查
記錄項目範例：
2018-01-01 09:01:37 4916 警告 ldap - 找不到群組：Name_Of_The_Group
提示：
a) LDAP 中沒有與該名稱相符的群組；新增該群組的正確 LDAP 名稱予以修正
b) 無法在宣告的 base_dn 中找到此群組 (請參閱 connector-ldap.yml 檔案)。 變更 base_dn 值以包含上述群組（主要發生在 base_dn 指向某個 OU 時，而不是盡可能廣泛）。
記錄項目範例：
2018-01-01 11:25:45 1 錯誤 umapi.action - 請求 ID 中的錯誤：action_1 (使用者：{'user': 'myuser@domain.com', 'useAdobeID': True, 'requestID': 'action_1'}，指令：{'add': {'product': ['group_name']}}): 代碼："error.group.not_found" 訊息："找不到群組 my_group_name"
提示：Adobe 端沒有上方輸出內容中的使用者群組 group_name，因此請建立此群組。 如果要設定 PLC 的名稱，而非使用者群組的名稱，請查看此文件頁面，取得更清楚的說明。
記錄項目範例：
2018-09-05 10:58:08 96329 關鍵 main - 連線到組織 some_Org_UUID@AdobeOrg 的端點 https://usermanagement.adobe.io/v2/usermanagement 失敗：dlopen(/Users/user/.pex/install/cryptography-2.3-cp37-cp37m-macosx_10_12_x86_64.whl.f77d5cc74b0deef9f1df7eacfe5f5ea57ed94a63/cryptography-2.3-cp37-cp37m-macosx_10_12_x86_64.whl/cryptography/hazmat/bindings/_openssl.abi3.so, 2)：未載入資料庫：/usr/local/opt/openssl/lib/libssl.1.0.0.dylib 參考來源：/Users/user/.pex/install/cryptography-2.3-cp37-cp37m-macosx_10_12_x86_64.whl.f77d5cc74b0deef9f1df7eacfe5f5ea57ed94a63/cryptography-2.3-cp37-cp37m-macosx_10_12_x86_64.whl/cryptography/hazmat/bindings/_openssl.abi3.so 原因：找不到映像檔 2018-09-05 10:58:08 96329 INFO main - ========== 結束執行 (User Sync 版本：2.3) (總時間：0:00:00)
提示：此錯誤是在 macOS High Sierra 上使用 UST v2.3 和 Python 3.7.0 時記錄的。在終端機中執行 brew install openssl 解決了這個特定情況。
記錄項目範例：
2019-07-28 07:17:51 2220 錯誤 umapi.action - 請求 ID 中的錯誤：action_1 (使用者：{'user': 'user@claimed-domain.com', 'requestID': 'action_1'}，指令：{'createFederatedID': {'email': 'user@claimed-domain.com', 'option': 'updateIfAlreadyExists', 'firstname': 'First', 'lastname': 'Last', 'country': 'US'}})：代碼："error.internal.create_failed" 訊息："無法為類型 2 或 3 建立個人。Renga 結果為 NOT_ALLOWED，資源由外部管理，且權杖缺少 GROUP_SOURCE_UPDATE 用途。"
有時 @claimed-domain.com 會由其他已設定 Azure 或 Google 連結器的組織持有，以管理將帳戶同步至 Admin Console 的作業。 此網域會託管給其他使用 User Sync Tool 同步 @claimed-domain.com 格式帳戶的組織。
原因：User Sync Tool 向 LDAP 伺服器擷取
user@claimed-domain.com帳戶，以在次要組織中建立帳戶時，記錄訊息就會顯示。 然而，此帳戶尚未透過 Azure 或 Google 連結器建立/同步至主要組織。
提示：嘗試在使用 Azure 或 Google 連結器的組織中建立/同步 user@claimed-domain.com 帳戶，然後在受信任的組織中使用 UST 再次同步。
記錄項目範例：
2018-09-05 10:58:08 96329 6348 關鍵 main - 讀取群組資訊時發生意外的 LDAP 失敗：{'desc': 'Referral', 'info': 'Referral:\nldap://domain.local/DC=sub,DC=domain,DC=local'}
可能原因：探討的群組位於子網域中，但 host 值為根網域之一。
提示：將 host 值變更為可找到使用者群組的任一子網域。 如果探討的使用者或群組位於根網域和其子網域，請在根網域使用全域目錄連接埠。 將子網域中的群組修改為「通用」而非「全域」。 host 值使用全域目錄的範例：ldap://domain.local:3268 或 ldaps://domain.local:3269
在最後這種情況中，如果使用全域目錄連接埠，請確認 base_dn 值沒有值：
base_dn: ""
記錄項目範例：
2020-08-20 12:00:00 1892 錯誤 main - 未處理的例外
raise RequestError(result)
umapi_client.error.RequestError：請求錯誤 (401)：{"lastPage":false,"result":"error.organization.invalid_id",
"message":"UNAUTHORIZED"}
這個錯誤出現在較舊的整合中。
解決方法：在 https://developer.adobe.com/console/projects 建立一個新的整合 (或專案)，與現有的、用於相同目的的整合並列。新整合將提供新的憑證，請務必在 connector-umapi.yml 檔案中更新這些憑證。金鑰對（私密金鑰/公開金鑰）很有可能被重新頒發，因此新的私密金鑰需要替換現有的私密金鑰。
記錄項目範例：
2021-01-01 18:00:00 14063 錯誤 umapi.action - 請求 ID 中的錯誤：action_19 (使用者：{'user': 'some_user', 'domain': some.domain', 'requestID': 'action_19'}，指令：{'createFederatedID': {'email': 'some_user@some.domain', 'option': 'ignoreIfAlreadyExists', 'firstname': 'FName', 'lastname': 'LName, 'country': 'GB'}})：代碼："error.internal.create_failed" 訊息："無法建立 createFederatedID 類型的人員"
這是多種原因的通用錯誤，但通常的問題是建立動作中使用的網域受到 Azure 或 Google 同步設定的影響。
如何檢查：使用系統管理員帳戶登入 Admin Console，然後按一下「設定」選單，再按一下包含該網域的目錄內部，然後按一下「同步」選單標籤
「同步」選單中是否有「同步來源」卡片？
如果是，解決方法取決於同步應如何繼續進行：
-> 如果應該由 Azure 或 Google 連接器進行同步，請繼續設定同步來源並完全移除 UST
-> 如果應該由 UST 進行同步，請按一下「前往設定」按鈕，然後按一下頁面底部的「移除同步」按鈕；之後 UST 應該會開始正常運作
如果否，則可能是目前 UST 針對一個主控台執行，該主控台中相關網域是由不同的主控台（所屬組織）委託的。這個其他組織可能已開啟 Azure 或 Google 同步，這可能導致目前的錯誤。在這種情況下，解決方法是先在擁有組織/主控台中同步帳戶，然後使用 UST 在目前的主控台中建立/新增帳戶。
如果以上情況都不符合目前的情況，最好聯絡企業支援。
