排查 Microsoft Fabric 中数据工厂的管道问题

本文探讨排查 Microsoft Fabric 中数据工厂的外部控制活动问题的常用方法。

连接器和复制活动

如果遇到连接器问题（例如，使用复制活动时遇到错误），请参阅排查连接器问题一文。

Azure Databricks

错误代码:3200

• 消息：错误 403。

• 原因：The Databricks access token has expired.

• 建议：默认情况下，Azure Databricks 访问令牌的有效期为 90 天。 创建新的令牌并更新连接。

错误代码:3201

• 消息：Missing required field: settings.task.notebook_task.notebook_path.

• 原因：Bad authoring: Notebook path not specified correctly.

• 建议：在 Databricks 活动中指定笔记本路径。

• 消息：Cluster... does not exist.

• 原因：Authoring error: Databricks cluster does not exist or has been deleted.

• 建议：验证 Databricks 群集是否存在。

• 消息：Invalid Python file URI... Please visit Databricks user guide for supported URI schemes.

• 原因：Bad authoring.

• 建议：为工作区寻址方案指定绝对路径，或者为 Databricks 文件系统 (DFS) 中存储的文件指定 dbfs:/folder/subfolder/foo.py。

• 消息：{0} LinkedService should have domain and accessToken as required properties.

• 原因：Bad authoring.

• 建议：验证连接定义。

• 消息：{0} LinkedService should specify either existing cluster ID or new cluster information for creation.

• 原因：Bad authoring.

• 建议：验证 [连接定义]/azure/data-factory/compute-linked-services#azure-databricks-linked-service)。

• 消息：Node type Standard_D16S_v3 is not supported. Supported node types: Standard_DS3_v2, Standard_DS4_v2, Standard_DS5_v2, Standard_D8s_v3, Standard_D16s_v3, Standard_D32s_v3, Standard_D64s_v3, Standard_D3_v2, Standard_D8_v3, Standard_D16_v3, Standard_D32_v3, Standard_D64_v3, Standard_D12_v2, Standard_D13_v2, Standard_D14_v2, Standard_D15_v2, Standard_DS12_v2, Standard_DS13_v2, Standard_DS14_v2, Standard_DS15_v2, Standard_E8s_v3, Standard_E16s_v3, Standard_E32s_v3, Standard_E64s_v3, Standard_L4s, Standard_L8s, Standard_L16s, Standard_L32s, Standard_F4s, Standard_F8s, Standard_F16s, Standard_H16, Standard_F4s_v2, Standard_F8s_v2, Standard_F16s_v2, Standard_F32s_v2, Standard_F64s_v2, Standard_F72s_v2, Standard_NC12, Standard_NC24, Standard_NC6s_v3, Standard_NC12s_v3, Standard_NC24s_v3, Standard_L8s_v2, Standard_L16s_v2, Standard_L32s_v2, Standard_L64s_v2, Standard_L80s_v2.

• 原因：Bad authoring.

• 建议：参考错误消息。

错误代码:3202

• 消息：There were already 1000 jobs created in past 3600 seconds, exceeding rate limit: 1000 job creations per 3600 seconds.

• 原因：Too many Databricks runs in an hour.

• 建议：检查将此 Databricks 工作区用于其作业创建速率的所有管道。 如果管道总共启动的 Databricks 运行数过多，请将一些管道迁移到新工作区。

• 消息：Could not parse request object: Expected 'key' and 'value' to be set for JSON map field base_parameters, got 'key: "..."' instead.

• 原因：Authoring error: No value provided for the parameter.

• 建议：检查管道 JSON，确保 baseParameters 笔记本中的所有参数指定非空值。

• 消息：User: SimpleUserContext{userId=..., name=user@company.com, orgId=...} is not authorized to access cluster.

• 原因：不允许已生成访问令牌的用户访问连接中指定的 Databricks 群集。

• 建议：确保该用户在工作区中拥有所需的权限。

• 消息：Job is not fully initialized yet. Please retry later.

• 原因：作业未初始化。

• 建议：请等待并稍后重试。

错误代码:3203

• 消息：The cluster is in Terminated state, not available to receive jobs. Please fix the cluster or retry later.

• 原因：群集已终止。 对于交互式群集，此问题可能是争用条件问题。

• 建议：若要避免此错误，请使用作业群集。

错误代码:3204

• 消息：Job execution failed.

• 原因：错误消息指出了各种问题，例如意外的群集状态或特定的活动。 往往不会显示任何错误消息。

• 建议：空值

错误代码：3208

• 消息：An error occurred while sending the request.

• 原因： 与 Databricks 服务的网络连接已中断。

• 建议：如果使用的是自承载数据工厂运行时，请确保来自数据工厂运行时节点的网络连接是可靠的。 如果使用的是 Azure 数据工厂运行时，重试通常可以解决问题。

布尔运行输出开始以字符串（而不是预期的整数）形式出现

• 症状：布尔运行输出开始以字符串形式（例如，"0" 或 "1"）出现，而不是以预期的整数形式（例如，0 或 1）出现。

  

  2021 年 9 月 28 日美国东部标准时间上午 9 点左右，当依赖此输出的管道开始出现故障时，你注意到这一变化。 没有对管道进行任何更改，并且布尔输出在故障发生之前按预期到达。

  

• 原因：这个问题是由最近的一项更改引起的，这是设计使然。 更改后，如果结果是以零开头的数字，数据工厂会将该数字转换为八进制值，这是一个 bug。 此数字一直为 0 或 1，这在此更改之前从未引起过问题。 因此，为了修复八进制转换的问题，字符串输出将按原样从 Notebook 运行传递。

• 建议：将 if 条件更改为类似于 的条件。

函数

错误代码：3602

• 消息：Invalid HttpMethod: '%method;'.

• 原因： 活动有效负载中指定的 Httpmethod 不受 Azure 函数活动的支持。

• 建议：支持的 Httpmethod 为：PUT、POST、GET、DELETE、OPTIONS、HEAD 和 TRACE。

错误代码：3603

• 消息：Response Content is not a valid JObject.

• 原因： 调用的 Azure 函数未在响应中返回 JSON 有效负载。 数据工厂和 Synapse 管道 Azure 函数活动仅支持 JSON 响应内容。

• 建议：更新 Azure 函数，以便返回有效的 JSON 有效负载，例如，C# 函数可以返回 (ActionResult)new OkObjectResult("{\"Id\":\"123\"}");

错误代码：3606

• 消息：Azure 函数活动缺少函数密钥。

• 原因： Azure 函数活动定义不完整。

• 建议：检查输入的 Azure 函数活动 JSON 定义是否包含名为 functionKey 的属性。

错误代码：3607

• 消息：Azure function activity missing function name.

• 原因： Azure 函数活动定义不完整。

• 建议：检查输入的 Azure 函数活动 JSON 定义是否包含名为 functionName 的属性。

错误代码：3608

• 消息：Call to provided Azure function '%FunctionName;' failed with status-'%statusCode;' and message - '%message;'.

• 原因：活动定义中的 Azure 函数详细信息可能不正确。

• 建议：修复 Azure 函数详细信息，然后重试。

错误代码：3609

• 消息：Azure function activity missing functionAppUrl.

• 原因： Azure 函数活动定义不完整。

• 建议：检查输入的 Azure 函数活动 JSON 定义是否包含名为 functionAppUrl 的属性。

错误代码：3610

• 消息：There was an error while calling endpoint.

• 原因：函数 URL 可能不正确。

• 建议：验证活动 JSON 中的 functionAppUrl 值是否正确，然后重试。

错误代码：3611

• 消息：Azure function activity missing Method in JSON.

• 原因： Azure 函数活动定义不完整。

• 建议：检查输入的 Azure 函数活动 JSON 定义是否包含名为 method 的属性。

错误代码：3612

• 消息：Azure function activity missing LinkedService definition in JSON.

• 原因： Azure 函数活动定义不完整。

• 建议：检查输入的 Azure 函数活动 JSON 定义是否包含连接详细信息。

Azure 机器学习

错误代码:4101

• 消息：AzureMLExecutePipeline activity '%activityName;' has invalid value for property '%propertyName;'.

• 原因：属性 %propertyName; 的定义格式错误或缺失。

• 建议：检查是否使用正确的数据在活动 %activityName; 中定义了属性 %propertyName;。

错误代码:4110

• 消息：AzureMLExecutePipeline activity missing LinkedService definition in JSON.

• 原因：AzureMLExecutePipeline 活动定义不完整。

• 建议：检查输入的 AzureMLExecutePipeline 活动 JSON 定义是否包含正确的连接详细信息。

错误代码:4111

• 消息：AzureMLExecutePipeline activity has wrong LinkedService type in JSON. Expected LinkedService type: '%expectedLinkedServiceType;', current LinkedService type: Expected LinkedService type: '%currentLinkedServiceType;'.

• 原因：活动定义不正确。

• 建议：检查输入的 AzureMLExecutePipeline 活动 JSON 定义是否包含正确的连接详细信息。

错误代码:4112

• 消息：AzureMLService connection has invalid value for property '%propertyName;'.

• 原因：属性“%propertyName;”的定义格式错误或缺失。

• 建议：检查连接是否使用正确的数据定义了属性 %propertyName;。

错误代码:4121

• 消息：Request sent to Azure Machine Learning for operation '%operation;' failed with http status code '%statusCode;'. Error message from Azure Machine Learning: '%externalMessage;'.

• 原因：用于访问 Azure 机器学习的凭据已过期。

• 建议：验证凭据是否有效，然后重试。

错误代码:4122

• 消息：Request sent to Azure Machine Learning for operation '%operation;' failed with http status code '%statusCode;'. Error message from Azure Machine Learning: '%externalMessage;'.

• 原因：Azure 机器学习连接中提供的凭据无效，或者没有操作权限。

• 建议：验证连接中的凭据是否有效，并有权访问 Azure 机器学习。

错误代码:4123

• 消息：Request sent to Azure Machine Learning for operation '%operation;' failed with http status code '%statusCode;'. Error message from Azure Machine Learning: '%externalMessage;'.

• 原因：活动的属性（例如 pipelineParameters）对于 Azure 机器学习 (ML) 管道无效。

• 建议：检查活动属性的值是否与连接中指定的已发布 Azure 机器学习管道的预期有效负载相匹配。

错误代码:4124

• 消息：Request sent to Azure Machine Learning for operation '%operation;' failed with http status code '%statusCode;'. Error message from Azure Machine Learning: '%externalMessage;'.

• 原因：已发布的 Azure 机器学习管道终结点不存在。

• 建议：验证连接中指定的已发布 Azure 机器学习管道终结点是否在 Azure 机器学习中存在。

错误代码:4125

• 消息：Request sent to Azure Machine Learning for operation '%operation;' failed with http status code '%statusCode;'. Error message from Azure Machine Learning: '%externalMessage;'.

• 原因：Azure 机器学习中出现服务器错误。

• 建议：请稍后重试。 如果问题持续出现，请联系 Azure 机器学习团队以获得帮助。

错误代码:4126

• 消息：Azure ML pipeline run failed with status: '%amlPipelineRunStatus;'. Azure ML pipeline run Id: '%amlPipelineRunId;'. Please check in Azure Machine Learning for more error logs.

• 原因：Azure 机器学习管道运行失败。

• 建议：检查 Azure 机器学习中的其他错误日志，然后修复 ML 管道。

通用

错误代码：2103

• 消息：Please provide value for the required property '%propertyName;'.

• 原因：尚未提供属性的必需值。

• 建议：提供消息中的值，然后重试。

错误代码：2104

• 消息：The type of the property '%propertyName;' is incorrect.

• 原因： 提供的属性类型不正确。

• 建议：修复属性的类型，然后重试。

错误代码：2105

• 消息：An invalid json is provided for property '%propertyName;'. Encountered an error while trying to parse: '%message;'.

• 原因： 属性的值无效，或未采用预期的格式。

• 建议：参阅属性的文档，并验证提供的值是否采用正确的格式和类型。

错误代码：2106

• 消息：The storage connection string is invalid. %errorMessage;

• 原因： 存储的连接字符串无效或格式不正确。

• 建议：转到 Azure 门户，找到你的存储，将连接字符串复制并粘贴到连接中，然后重试。

错误代码：2110

• 消息：The connection type '%linkedServiceType;' is not supported for '%executorType;' activities.

• 原因：活动中指定的连接不正确。

• 建议：验证连接类型是否为活动支持的类型之一。

错误代码：2111

• 消息：The type of the property '%propertyName;' is incorrect. The expected type is %expectedType;.

• 原因： 提供的属性的类型不正确。

• 建议：修复属性类型，然后重试。

错误代码：2112

• 消息：The cloud type is unsupported or could not be determined for storage from the EndpointSuffix '%endpointSuffix;'.

• 原因： 云类型不受支持，或者对于 EndpointSuffix 中的存储来说无法确定。

• 建议：使用另一个云中的存储，然后重试。

Azure Batch (Azure 批处理)

下表适用于 Azure Batch。

错误代码：2500

• 消息：Hit unexpected exception and execution failed.

• 原因：Can't launch command, or the program returned an error code.

• 建议：确保可执行文件存在。 如果程序已启动，请验证是否已将 stdout.txt 和 stderr.txt 上传到存储帐户。 良好的做法是在代码中包含用于调试的日志。

错误代码：2501

• 消息：Cannot access user batch account; please check batch account settings.

• 原因： Batch 访问密钥或池名称不正确。

• 建议：验证连接中的池名称和 Batch 访问密钥。

错误代码：2502

• 消息：Cannot access user storage account; please check storage account settings.

• 原因： 存储帐户名称或访问密钥不正确。

• 建议：验证连接中的存储帐户名称和访问密钥。

错误代码：2504

• 消息：Operation returned an invalid status code 'BadRequest'.

• 原因：自定义活动的 folderPath 中的文件过多。 resourceFiles 的总大小不能超过 32,768 个字符。

• 建议：删除不必要的文件。或者压缩文件，并添加一个解压缩命令来解压缩文件。

  例如，使用 powershell.exe -nologo -noprofile -command "& { Add-Type -A 'System.IO.Compression.FileSystem'; [IO.Compression.ZipFile]::ExtractToDirectory($zipFile, $folder); }" ; $folder\yourProgram.exe

错误代码：2505

• 消息：Cannot create Shared Access Signature unless Account Key credentials are used.

• 原因：Azure Batch 活动仅支持使用访问密钥的存储帐户。

• 建议：请参阅错误说明。

错误代码：2507

• 消息：The folder path does not exist or is empty: ...

• 原因： 存储帐户的指定路径下没有文件。

• 建议：文件夹路径必须包含要运行的可执行文件。

错误代码：2508

• 消息：There are duplicate files in the resource folder.

• 原因： folderPath 的不同子文件夹中存在多个同名的文件。

• 建议：Azure Batch 活动平展 folderPath 下的文件夹结构。 如果需要保留文件夹结构，请压缩文件，并使用一个解压缩命令将其解压缩到 Azure Batch 中。

  例如，使用 powershell.exe -nologo -noprofile -command "& { Add-Type -A 'System.IO.Compression.FileSystem'; [IO.Compression.ZipFile]::ExtractToDirectory($zipFile, $folder); }" ; $folder\yourProgram.exe

错误代码：2509

• 消息：Batch url ... is invalid; it must be in Uri format.

• 原因： Batch URL 必须类似于 https://mybatchaccount.eastus.batch.azure.com

• 建议：请参阅错误说明。

错误代码：2510

• 消息：An error occurred while sending the request.

• 原因： Batch URL 无效。

• 建议：验证 Batch URL。

Web 活动

错误代码：2001

• 消息：The length of execution output is over limit (around 4MB currently).

• 原因：执行输出大于 4 MB，但支持的最大输出响应有效负载为 4 MB。

• 建议：确保执行输出大小不超过 4 MB。 有关详细信息，请参阅如何横向扩展使用数据工厂移动的数据的大小。

错误代码：2002

• 消息：The payload including configurations on activity/data/connection is too large. Please check if you have settings with very large value and try to reduce its size.

• 原因：尝试发送的有效负载太大。

• 建议：请参阅有效负载过大。

错误代码：2003

• 消息：There are substantial concurrent external activity executions which is causing failures due to throttling under subscription <subscription id>, region <region code> and limitation <current limit>. Please reduce the concurrent executions. For limits, refer https://aka.ms/adflimits.

• 原因：同时运行的活动过多。 同时触发过多管道时，可能会发生这种情况。

• 建议：减少管道并发。 可能需要分配管道的触发时间。

错误代码：2105

• 消息：The value type '<provided data type>', in key '<key name>' is not expected type '<expected data type>'

• 原因：动态内容表达式中生成的数据与键不匹配，导致 JSON 分析失败。

• 建议：查看关键字段并修复动态内容定义。

错误代码：2108

• 消息：Error calling the endpoint '<URL>'. Response status code: 'NA - Unknown'. More details: Exception message: 'NA - Unknown [ClientSideException] Invalid Url: <URL>. Please verify Url or Data Factory runtime is valid and retry. Localhost URLs are allowed only with SelfHosted Data Factory runtime'

• 原因：无法访问提供的 URL。 发生这种情况的原因可能是存在网络连接问题、无法分析 URL 或 Azure 数据工厂运行时上正在使用 localhost URL。

• 建议：验证是否可以访问提供的 URL。

• 消息：Error calling the endpoint '%url;'. Response status code: '%code;'

• 原因： 某个根本性问题（例如网络连接问题、DNS 失败、服务器证书验证问题或超时）导致请求失败。

• 建议：使用 Fiddler/Netmon/Wireshark 验证请求。

  使用 Fiddler

  若要使用 Fiddler 创建受监视 Web 应用程序的 HTTP 会话，请执行以下步骤：

  1. 下载、安装并打开 Fiddler。

  2. 如果 Web 应用程序使用 HTTPS，请转到“工具”“Fiddler 选项”>“HTTPS”。>

     1. 在“HTTPS”选项卡中，选择“捕获 HTTPS 连接”和“解密 HTTPS 流量”。

        

  3. 如果应用程序使用 TLS/SSL 证书，请将 Fiddler 证书添加到设备。

     请转到：“工具”“Fiddler 选项” > “HTTPS”>“操作”“将根证书导出到桌面”。>>>

  4. 转到“文件”“捕获流量”来关闭捕获。> 或者按 F12。

  5. 清除浏览器缓存以删除所有已缓存的项；必须重新下载这些项。

  6. 创建请求：

  7. 选择“编辑器”选项卡。

     1. 设置 HTTP 方法和 URL。

     2. 根据需要添加标头和请求正文。

     3. 选择“执行”。

  8. 再次打开流量捕获，并在页面上完成出问题的事务。

  9. 请转到：“文件”“保存”>“所有会话”。>

  有关详细信息，请参阅 Fiddler 入门。

错误代码：2113

• 消息：ExtractAuthorizationCertificate: Unable to generate a certificate from a Base64 string/password combination

• 原因：无法根据 Base64 字符串/密码组合生成证书。

• 建议：验证使用的 Base64 编码 PFX 证书和密码组合是否正确。

错误代码：2403

• 消息：Get access token from MSI failed for Datafactory <DF mname>, region <region code>. Please verify resource url is valid and retry.

• 原因：无法从提供的资源 URL 获取访问令牌。

• 建议：验证是否为托管标识提供了正确的资源 URL。

常规

REST 延续令牌 NULL 错误

错误消息： {"token":null,"range":{"min":..}

原因：跨多个分区/页面查询时，后端服务返回 JObject 格式的延续令牌，具有三个属性：令牌、最小和最大密钥范围，例如 {"token":null,"range":{"min":"05C1E9AB0DAD76","max":"05C1E9CD673398"}})。 根据源数据，查询结果可能为 0，这表示缺少令牌，尽管要提取的数据更多。

建议：当 continuationToken 不为空时，如字符串 {"token":null,"range":{"min":"05C1E9AB0DAD76","max":"05C1E9CD673398"}}，需要使用上一个响应中的延续令牌再次调用 queryActivityRuns API。 你需要再次为查询 API 传递完整的字符串。 这些活动将在查询结果的后续页面中返回。 只要完整的 continuationToken 值不为 null，需要继续查询，那么便可以忽略此页面中的空数组。 更多详情，请参阅 管道运行查询的 REST API。

活动停滞问题

如果观察到活动运行的时间比正常运行的时间长得多，并且几乎没有任何进展，则可能是停滞。 你可以尝试取消它，然后重试，看是否有帮助。 如果是复制活动，则可以参阅排查复制活动的性能问题一文，了解性能监视和故障排除；如果是数据流，请参阅映射数据流性能和优化指南。

有效负载太大

错误消息：The payload including configurations on activity/data/connection is too large. Please check if you have settings with very large value and try to reduce its size.

原因：每个活动运行的有效负载包括活动配置、关联的数据和连接配置（如果有），以及为每个活动类型生成的系统属性的一小部分。 如数据工厂和 Azure Synapse Analytics 的 Azure 限制文档中所述，此类有效负载大小限制为 896 KB。

建议： 达到此限制，很可能是因为从上游活动输出或外部传入了一个或多个大参数值，尤其是在控制流中跨活动传递实际数据时。 请检查是否可以减小大参数值，或调整管道逻辑以避免跨活动传递此类值，而改为在活动内处理此类值。

不受支持的压缩导致文件损坏

症状：你尝试解压缩存储在 blob 容器中的文件。 管道中的单个复制活动有一个压缩类型设置为“deflate64”（或任何不受支持的类型）的源。 此活动成功运行并生成包含在 zip 文件中的文本文件。 但是，文件中的文本有问题，该文件似乎已损坏。 此文件在本地解压缩时，是正常的。

原因：zip 文件由“deflate64”算法压缩，而数据工厂的内部 zip 库只支持“deflate”。如果 zip 文件由 Windows 系统压缩，并且整体文件大小超过特定数量，则 Windows 默认使用“deflate64”，但数据工厂不支持此算法。 另一方面，如果文件较小或使用某些支持指定压缩算法的第三方 zip 工具，Windows 将默认使用“deflate”。

提示

实际上，数据工厂和 Synapse Analytics 中的二进制格式和数据工厂和 Azure Synapse Analytics 中带分隔符的文本格式都明确指出，数据工厂不支持“deflate64”格式。

执行管道会将数组参数作为字符串传递给子管道

错误消息：Operation on target ForEach1 failed: The execution of template action 'MainForEach1' failed: the result of the evaluation of 'foreach' expression '@pipeline().parameters.<parameterName>' is of type 'String'. The result must be a valid array.

原因：即使在“执行管道”中创建数组类型的参数（如下图所示），管道也会失败。

这是因为有效负载作为字符串从父管道传递到子管道。 当我们检查传递给子管道的输入时，我们可以看到它。

建议：要解决此问题，可以利用创建数组函数，如下图所示。

然后，管道将会成功。 在输入框中我们可以看到，传递的参数是一个数组。

相关内容

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

• 数据工厂博客
• 数据工厂功能请求
• 数据工厂 Stack Overflow 论坛
• Twitter 中有关数据工厂的信息
• Azure 视频
• Microsoft Q&A 问题页