查找常见的 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。
此错误记录于 macOS High Sierra，使用 User Sync Tool v2.3 和 Python 3.7.0。 在终端中运行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 值是根域之一。将 host 值更改为包含用户组的子域。如果用户或组既在根域中又在其子域中，请在根域上使用全局目录端口，并将子域组从全局更改为通用。使用全局目录的示例主机值：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 的其他组织拥有，然后该域被信任给使用 User Sync Tool 同步 @claimed-domain.com 格式帐户的其他组织。当工具从 LDAP 服务器提取 user@claimed-domain.com 帐户以在辅助组织中创建该帐户，但该帐户尚未通过 Azure 或 Google 连接器在主要组织中创建或同步时，会显示此消息。在使用 Azure 或 Google 连接器的组织中创建或同步 user@claimed-domain.com 帐户，然后在受托组织中使用 User Sync Tool 重试同步。
此通用错误有多种原因，但通常的故障是创建操作中使用的域处于 Azure 或 Google 同步设置下。要检查，请使用系统管理员帐户登录 Adobe Admin Console，前往"设置"，选择包含该域的目录，然后选择"同步"选项卡。如果存在同步源卡片，修复方法取决于同步应如何继续：
- 如果 Azure 或 Google 连接器应执行同步，请继续进行同步来源设置并完全删除用户同步工具。
- 如果用户同步工具应执行同步，请选择"前往设置"，然后选择页面底部的"删除同步"。然后工具将正常运行。
如果不存在同步来源信息卡，当前工具可能在某个控制台上运行，该控制台的域从不同的控制台（拥有组织）获得委托。该组织可能已开启 Azure 或 Google 同步，这会导致此错误。请先在帐户所属的 Console 中同步帐户，然后使用该工具在当前 Console 中创建帐户。
如果以上都不适用，请联系企业支持。
