排查 Azure 数据工厂和 Azure Synapse 中的 FTP、SFTP 和 HTTP 连接器问题

适用于： Azure 数据工厂 Azure Synapse Analytics

本文提供有关排查 Azure 数据工厂和 Azure Synapse 中常见的 FTP、SFTP 和 HTTP 连接器问题的建议。

FTP

错误代码：FtpFailedToConnectToFtpServer

• 消息：Failed to connect to FTP server. Please make sure the provided server information is correct, and try again.

• 原因：对 FTP 服务器使用的链接服务类型可能不正确，例如使用安全 FTP (SFTP) 链接服务连接到 FTP 服务器。

• 建议：检查目标服务器的端口。 FTP 使用端口 21。

错误代码：FtpFailedToReadFtpData

• 消息：Failed to read data from ftp: The remote server returned an error: 227 Entering Passive Mode (*,*,*,*,*,*).

• 原因：对于数据工厂或 Synapse 管道支持的被动模式下的数据传输，未打开端口范围 1024 到 65535。

• 建议：检查目标服务器的防火墙设置。 打开端口 1024-65535 或在 FTP 服务器中将端口范围指定为 SHIR/Azure IR IP 地址。

SFTP

错误代码：SftpOperationFail

• 消息：Failed to '%operation;'. Check detailed error from SFTP.

• 原因：SFTP 操作出现问题。

• 建议：检查来自 SFTP 的错误详细信息。

错误代码：SftpRenameOperationFail

• 消息：Failed to rename the temp file. Your SFTP server doesn't support renaming temp file, set "useTempFileRename" as false in copy sink to disable uploading to temp file.

• 原因：SFTP 服务器不支持重命名临时文件。

• 建议：在复制接收器中将“useTempFileRename”设置为 false，以禁止上传到临时文件。

错误代码：SftpInvalidSftpCredential

• 消息：Invalid SFTP credential provided for '%type;' authentication type.

• 原因：私钥内容是从 Azure 密钥保管库或 SDK 提取的，但编码有误。

• 建议：

  如果私钥内容来自密钥保管库，则在将原始密钥文件直接上传到 SFTP 链接服务时，该文件有效。

  有关详细信息，请参阅使用数据工厂或 Synapse 管道从/向 SFTP 服务器复制数据。 私钥内容是 base64 编码的 SSH 私钥内容。

  请使用 base64 编码对整个原始私钥文件进行编码，并将已编码的字符串存储在密钥保管库中。 如果选择从文件上传，则可在 SFTP 链接服务上使用原始私钥文件。

  下面是可用于生成字符串的一些示例：

  • 使用 C# 代码：

    byte[] keyContentBytes = File.ReadAllBytes(Private Key Path);
    string keyContent = Convert.ToBase64String(keyContentBytes, Base64FormattingOptions.None);
    

  • 使用 Python 代码：

    import base64
    rfd = open(r'{Private Key Path}', 'rb')
    keyContent = rfd.read()
    rfd.close()
    print base64.b64encode(Key Content)
    

  • 使用第三方 base64 转换工具。 建议使用编码为 Base64 格式工具。

• 原因：选择的密钥内容格式有误。

• 建议：

  当前不支持使用 PKCS#8 格式的 SSH 私钥（开头为“-----BEGIN ENCRYPTED PRIVATE KEY-----”）访问 SFTP 服务器。

  若要将密钥转换为传统的 SSH 密钥格式（开头为“-----BEGIN RSA PRIVATE KEY-----”），请运行以下命令：

  openssl pkcs8 -in pkcs8_format_key_file -out traditional_format_key_file
  chmod 600 traditional_format_key_file
  ssh-keygen -f traditional_format_key_file -p
  

• 原因：凭据或私钥内容无效。

• 建议：若要查看密钥文件或密码是否正确，请使用 WinSCP 等工具仔细检查。

SFTP 复制活动失败

• 症状：

  • 错误代码：UserErrorInvalidColumnMappingColumnNotFound
  • 错误消息：Column 'AccMngr' specified in column mapping cannot be found in source data.

• 原因：源不包含名为“AccMngr”的列。

• 解决方法：若要确定“AccMngr”列是否存在，请映射目标数据集列来仔细检查数据集配置。

错误代码：SftpFailedToConnectToSftpServer

• 消息：Failed to connect to SFTP server '%server;'.

• 原因：如果错误消息包含“套接字读取操作在 30,000 毫秒后超时”这一字符串，则可能是由于对 SFTP 服务器使用了错误的链接服务类型而导致的。 例如，你可能正在使用 FTP 链接服务连接到 SFTP 服务器。

• 建议：检查目标服务器的端口。 SFTP 默认使用端口 22。

• 原因：如果错误消息包含“服务器响应不包含 SSH 协议标识”这一字符串，则可能是由于 SFTP 服务器限制了连接而导致的。 创建了多个连接来从 SFTP 服务器并行下载，有时会遇到 SFTP 服务器限制。 通常，不同的服务器在遇到限制时会返回不同的错误。

• 建议：

  将 SFTP 数据集的最大并发连接数指定为 1，然后重新运行复制活动。 如果活动成功，则可确定这是限制导致的。

  若要提升低吞吐量，请与 SFTP 管理员联系以增加并发连接计数限制，或者可执行以下操作之一：

  • 如果使用自承载 IR，请将自承载 IR 计算机的 IP 添加到允许列表中。
  • 如果使用的是 Azure IR，请添加 Azure Integration Runtime IP 地址。 如果不想将一系列 IP 添加到 SFTP 服务器允许列表中，请改用自承载 IR。

错误代码：SftpPermissionDenied

• 消息：Permission denied to access '%path;'

• 原因：指定的用户在操作时没有对文件夹或文件的读取或写入权限。

• 建议：授予用户对 SFTP 服务器上文件夹或文件的读取或写入权限。

错误代码：SftpAuthenticationFailure

• 消息：Meet authentication failure when connect to Sftp server '%server;' using '%type;' authentication type. Please make sure you are using the correct authentication type and the credential is valid. For more details, see our troubleshooting docs.

• 原因：指定的凭据（密码或私钥）无效。

• 建议：检查凭据。

• 原因：指定的身份验证类型不被允许或不足以在 SFTP 服务器中完成身份验证。

• 建议：应用以下选项以使用正确的身份验证类型：

  • 如果服务器需要密码，请使用“基本”。
  • 如果服务器需要私钥，请使用“SSH 公钥身份验证”。
  • 如果服务器需要“密码”和“私钥”，请使用“多重身份验证”。

• 原因： SFTP 服务器需要“键盘 - 交互式”身份验证，但提供的是“密码”。

• 建议：

  “键盘 - 交互式”是一种特殊的身份验证方法，不同于“密码”。 这意味着登录服务器时，必须手动输入密码，并且无法使用之前保存的密码。 但 Azure 数据工厂 (ADF) 是一项计划的数据传输服务，并且它没有可以让你在运行时提供密码的弹出输入框。
  

  作为一个折衷方案，系统提供了一个选项来模拟后台的输入，而不是实际的手动输入，这等效于将“键盘 - 交互式”更改为“密码”。 如果可以接受此安全问题，请按照以下步骤进行启用：
  

  1. 在 ADF 门户中，将鼠标悬停在 SFTP 链接服务上，并通过选择“代码”按钮打开其有效负载。
  2. 在“typeProperties”部分中添加 "allowKeyboardInteractiveAuth": true。

由于 ADF 不支持 SFTP 提供的密钥交换算法，无法连接到 SFTP

• 症状：无法通过 ADF 连接到 SFTP，并收到以下错误消息：Failed to negotiate key exchange algorithm.

• 原因：ADF 不支持 SFTP 服务器提供的密钥交换算法。 ADF 支持的密钥交换算法包括：

  • curve25519-sha256
  • curve25519-sha256@libssh.org
  • ecdh-sha2-nistp256
  • ecdh-sha2-nistp384
  • ecdh-sha2-nistp521
  • diffie-hellman-group-exchange-sha256
  • diffie-hellman-group-exchange-sha1
  • diffie-hellman-group16-sha512
  • diffie-hellman-group14-sha256
  • diffie-hellman-group14-sha1
  • diffie-hellman-group1-sha1

  SHIR 上支持上述密钥交换算法的最新版本为版本 5.19。

错误代码：SftpInvalidHostKeyFingerprint

• 消息：Host key finger-print validation failed. Expected fingerprint is '<value in linked service>', real finger-print is '<server real value>'

• 原因：Azure 数据工厂现在支持 SFTP 连接器中更安全的主机密钥算法。 对于新添加的算法，需要在 SFTP 服务器中获取相应的指纹。

  新增的支持算法包括：

  • ssh-ed25519
  • ecdsa-sha2-nistp256
  • ecdsa-sha2-nistp384
  • ecdsa-sha2-nistp521

• 建议：使用 real finger-print 中的主机键名从 SFTP 服务器的错误消息中获取有效指纹。 可以运行该命令获取 SFTP 服务器上的指纹。 例如：在 Linux 服务器运行 ssh-keygen -E md5 -lf <keyFilePath> 以获取指纹。 该命令可能因不同的服务器类型而异。

错误代码：UnsupportedCompressionTypeWhenDisableChunking

• 消息："Disable chunking" is not compatible with "ZipDeflate" decompression.

• 原因：禁用区块与 ZipDeflate 解压缩不兼容。

• 建议：将二进制数据加载到临时区域（例如Azure Blob 存储），并在另一个复制活动中解压缩它们。

HTTP

错误代码：HttpFileFailedToRead

• 消息：Failed to read data from http server. Check the error from http server:%message;

• 原因：当数据工厂或 Synapse 管道与 HTTP 服务器通信时，如果 HTTP 请求操作失败，则会发生此错误。

• 建议：查看错误消息中的 HTTP 状态代码，并修复远程服务器问题。

错误代码：HttpSourceUnsupportedStatusCode

• 消息：Http source doesn't support HTTP Status Code '%code;'.

• 原因：当 Azure 数据工厂请求 HTTP 源但收到意外的状态代码时，会发生此错误。

• 建议：有关 HTTP 状态代码的详细信息，请参阅此文档。

相关内容

尝试通过以下资源获得故障排除方面的更多帮助：

• 连接器故障排除指南
• 数据工厂 Stack Overflow 论坛