你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
适用于：
Azure 数据工厂 Azure Synapse Analytics
提示
试用 Microsoft Fabric 中的数据工厂，这是一种适用于企业的一站式分析解决方案。 Microsoft Fabric 涵盖从数据移动到数据科学、实时分析、商业智能和报告的所有内容。 了解如何免费开始新的试用！
本文介绍了排查 Azure 数据工厂与 Synapse Analytics 中持续集成和持续部署 (CI-CD)、Azure DevOps 和 GitHub 问题的常用方法。
如果在使用源代码管理或 DevOps 技术方面有疑问或问题，下面是一些可能有用的文章：
常见错误和消息
由于租户不同，连接到 Git 存储库失败
问题
有时会遇到 HTTP 状态 401 等身份验证问题。 特别是在多个租户具有来宾帐户的时候，情况可能变得更加复杂。
原因
从原始租户那里获得了令牌，但服务位于来宾租户，同时尝试使用该令牌来访问来宾租户中的 DevOps。 这种类型的令牌访问不是预期的行为。
建议
应使用从来宾租户颁发的令牌。 例如，必须为来宾租户和 DevOps 分配相同的 Microsoft Entra ID，以便其可以正确设置令牌行为并使用正确的租户。
参数文件中的模板参数无效
问题
如果我们删除开发分支中的触发器，而该触发器已在具有相同配置（如频率和间隔）的测试或生产分支中可用，那么发布管道部署将成功，并且相应的触发器将在各自环境中删除。 但是，如果测试/生产环境中使用的配置（如频率和间隔）不同，并且在开发环境中删除相同的触发器，那么部署将失败并出现错误。
原因
CI/CD 管道失败并出现以下错误：
2020-07-20T11:19:02.1276769Z ##[error]Deployment template validation failed: 'The template parameters 'Trigger_Salesforce_properties_typeProperties_recurrence_frequency, Trigger_Salesforce_properties_typeProperties_recurrence_interval, Trigger_Salesforce_properties_typeProperties_recurrence_startTime, Trigger_Salesforce_properties_typeProperties_recurrence_timeZone' in the parameters file are not valid; they are not present in the original template and can therefore not be provided at deployment time. The only supported parameters for this template are 'factoryName, PlanonDWH_connectionString, PlanonKeyVault_properties_typeProperties_baseUrl
建议
发生此错误的原因是，我们经常删除已参数化的触发器，因此参数将在 Azure 资源管理器 (ARM) 模板中不可用（因为该触发器不复存在）。 由于 ARM 模板不再包含参数，因此需要更新 DevOps 管道中已重写的参数。 否则，每次更改 ARM 模板中的参数时，必须更新 DevOps 管道中的重写参数（在部署任务中）。
不支持更新属性类型
问题
CI/CD 发布管道失败，出现以下错误：
2020-07-06T09:50:50.8716614Z There were errors in your deployment. Error code: DeploymentFailed.
2020-07-06T09:50:50.8760242Z ##[error]At least one resource deployment operation failed. Please list deployment operations for details. Please see https://aka.ms/DeployOperations for usage details.
2020-07-06T09:50:50.8771655Z ##[error]Details:
2020-07-06T09:50:50.8772837Z ##[error]DataFactoryPropertyUpdateNotSupported: Updating property type is not supported.
2020-07-06T09:50:50.8774148Z ##[error]DataFactoryPropertyUpdateNotSupported: Updating property type is not supported.
2020-07-06T09:50:50.8775530Z ##[error]Check out the troubleshooting guide to see if your issue is addressed: https://learn.microsoft.com/azure/devops/pipelines/tasks/deploy/azure-resource-group-deployment#troubleshooting
2020-07-06T09:50:50.8776801Z ##[error]Task failed while creating or updating the template deployment.
原因
出现此错误是因为目标服务实例中同名的集成运行时的类型不同。 部署期间集成运行时的类型必须相同。
建议
请参阅 CI/CD 的最佳做法
集成运行时不会经常更改，并且在 CI/CD 中的所有阶段类似，因此服务需要集成运行时在 CI/CD 的所有阶段都具有相同的名称和类型。 如果名称、类型和属性不同，请确保匹配源和目标集成运行时配置，然后部署发布管道。
若要在所有阶段中共享集成运行时，请考虑使用三元工厂，这只是为了包含共享的集成运行时。 可以在所有环境中将此共享工厂用作链接的集成运行时类型。
由于无效的引用，文档创建或更新失败
问题
尝试发布更改时收到以下错误消息：
"error": { "code": "BadRequest", "message": "The document creation or update failed because of invalid reference '<entity>'.", "target": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/<rgname>/providers/Microsoft.DataFactory/factories/<datafactory>/pipelines/<pipeline>", "details": null }
原因
已拆离 Git 配置，并且在选择了“重要资源”标志的情况下再次对其进行设置，这会将服务设置为“同步”。 这意味着在发布过程中没有发生任何更改。
解决方法
取消 Git 配置并再次进行设置，并确保不选中“导入现有资源”复选框。
数据工厂从一个资源组移动到另一个资源组失败
问题
无法将数据工厂从一个资源组移到另一个资源组，该操作会失败并出现以下错误：{ "code": "ResourceMoveProviderValidationFailed", "message": "Resource move validation failed. Please see details. Diagnostic information: timestamp 'xxxxxxxxxxxxZ', subscription id 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', tracking id 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', request correlation id 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'.", "details": [ { "code": "BadRequest", "target": "Microsoft.DataFactory/factories", "message": "One of the resources contain integration runtimes that are either SSIS-IRs in starting/started/stopping state, or Self-Hosted IRs which are shared with other resources. Resource move is not supported for those resources." } ] }
解决方法
需要删除 SSIS-IR 和共享 IR 才能允许移动操作。 如果不想删除集成运行时，最好的方法是遵循复制和克隆文档中的操作来完成复制，并在完成后删除旧的数据工厂。
无法导出和导入 ARM 模板
问题
无法导出和导入 ARM 模板。 门户上没有错误，但在浏览器跟踪中可能会看到以下错误：
Failed to load resource: the server responded with a status code of 401 (Unauthorized)
原因
你创建了一个客户角色作为用户，但该角色没有必要的权限。 加载 UI 时，将检查工厂的一系列公开控制值。 这种情况下，用户的访问角色无权访问 queryFeaturesValue API。 若要访问此 API，请关闭全局参数功能。 ARM 模板导出代码路径部分依赖于全局参数功能。
解决方法
为了解决此问题，需要将以下权限添加到角色：Microsoft.DataFactory/factories/queryFeaturesValue/action。 默认情况下，此权限包含在“数据工厂参与者”角色（适用于数据工厂）和“参与者”角色（适用于 Synapse Analytics）中 。
无法针对 CI/CD 进行自动发布
原因
在不久前，还只能通过在门户中单击 UI 来为部署发布管道。 现在可以自动完成此过程。
解决方法
CI/CD 过程已增强。 自动发布功能从 UI 中提取、验证和导出所有 ARM 模板功能。 此功能通过一个公开可用的 NPM 包 @microsoft/Azure-data-factory-utilities 实现了逻辑的可用性。 你可以使用此方法以编程方式触发这些操作，而无需转到 UI 并选择按钮。 此方法为 CI/CD 管道提供了真正的持续集成体验。 有关详细信息，请参阅 CI/CD 发布改进。
由于 4 MB ARM 模板限制而无法发布
问题
无法部署，因为达到了 Azure 资源管理器模板 4 MB 的总大小限制。 需要在超过限制后部署解决方案。
原因
Azure 资源管理器将模板大小限制为 4 MB。 将模板大小限制为 4 MB 以内，每个参数文件大小限制为 64 KB 以内。 4-MB 限制适用于模板使用迭代资源定义以及变量和参数值进行扩展后的最终状态。 但已经超出了限制。
解决方法
对于中小型解决方案，单个模板更易于理解和维护。 可以查看单个文件中的所有资源和值。 对于高级方案，使用链接模板可将解决方案分解为目标组件。 请遵循使用链接模板和嵌套模板的最佳做法。
DevOps API 限制为 20 MB，导致 ADF 触发两次或多次，而不是一次
问题
发布资源时，Azure 管道会触发两次或多次，而不是一次。
原因
Azure DevOps 有 20 MB 的 REST API 限制。 当 ARM 模板超出此大小时，ADF 在内部将模板文件拆分为包含链接模板的多个文件，以解决此问题。 副作用就是，此拆分可能会导致客户的触发器多次运行。
解决方法
使用 ADF“自动发布”（首选）或“手动触发器”方法触发一次，而不是两次或更多次。
无法连接到 GIT Enterprise
问题
由于权限问题，无法连接到 GIT Enterprise。 可以看到“422 - 无法处理的实体”之类的错误。
原因
- 尚未为服务配置 OAuth。
- URL 配置错误。 repoConfiguration 应为 FactoryGitHubConfiguration 类型
解决方法
首先向服务授予 OAuth 访问权限。 然后，需要使用正确的 URL 连接到 GIT Enterprise。 该配置必须设置为客户组织。 例如，服务将首先尝试 https://hostname/api/v3/search/repositories?q=user%3<customer credential>....，但会失败。 然后，它将尝试 https://hostname/api/v3/orgs/<org>/<repo>... 并成功。
无法从已删除的实例恢复
问题
删除了服务实例或包含该实例的资源组，现在需要对其进行恢复。
原因
仅当使用 DevOps 或 Git 为实例配置了源代码管理时，才可以恢复该实例。 此操作会引入所有最新发布的资源，但不会还原任何未发布的管道、数据集或链接服务。 如果没有源代码管理，则无法从 Azure 后端恢复已删除的实例，因为一旦服务收到 delete 命令，就会永久删除该实例且不进行任何备份。
解决方法
若要恢复配置了源代码管理的已删除服务实例，请参考以下步骤：
创建服务的新实例。
使用相同的设置重新配置 Git，但请确保将现有资源导入所选存储库，然后选择“新建分支”。
创建拉取请求以将更改合并到协作分支并发布。
如果已删除的数据工厂或 Synapse 工作区中有自承载集成运行时，则必须在新的工厂或工作区中创建 IR 的新实例。 必须卸载再重新安装本地或虚拟机 IR 实例，并获取新密钥。 在安装完新 IR 后，必须将链接服务更新为指向新 IR，然后再次测试连接，否则会失败并出现错误“引用无效”。
无法使用自动发布方法部署到不同的阶段
问题
客户遵循了所有必要的步骤（例如使用 Azure DevOps 安装 NPM 包并设置更高的阶段），但部署仍然失败。
原因
尽管可以通过多种方式使用 npm 包，但其中一个主要优势是通过 Azure 管道使用的。 每次合并到协作分支中时，都可以触发一个管道，该管道首先验证所有代码，然后将 ARM 模板导出到可由发布管道使用的生成项目。 在 Starter 管道中，YAML 文件应该有效且完整。
解决方法
package.json 文件夹无效，因此以下部分无效。
- task: Npm@1
inputs:
command: 'custom'
workingDir: '$(Build.Repository.LocalPath)/<folder-of-the-package.json-file>' #replace with the package.json folder
customCommand: 'run build validate $(Build.Repository.LocalPath) /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/testResourceGroup/providers/Microsoft.DataFactory/factories/yourFactoryName'
displayName: 'Validate'
应将 DataFactory 包含在 customCommand 中，例如“run build validate $(Build.Repository.LocalPath)/DataFactory/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/testResourceGroup/providers/Microsoft.DataFactory/factories/yourFactoryName”。 请确保生成的用于更高阶段的 YAML 文件包含必需的 JSON 项目。
已发布的 JSON 文件中显示额外的左 [
问题
通过 DevOps 发布时，显示了一个多余的 [。 服务自动在 DevOps 的 ARMTemplate 中添加了一个多余的 [。 你将在 JSON 文件中看到类似 [[ 的表达式。
原因
由于 [ 是 ARM 模板的保留字符，因此会自动添加一个额外的 [ 来对 [ 进行转义。
解决方法
对于 CI/CD，这是发布过程中的正常行为。
在管道运行的进度/排队阶段执行 CI/CD
问题
你想要在管道运行的进度和排队阶段执行 CI/CD。
原因
当管道处于进度/排队阶段时，你首先需要监视管道和活动。 然后，可以决定等待管道完成，也可以取消管道运行。
解决方法
可以使用 SDK、Azure Monitor 或 Monitor 来监视管道。 然后，可以进一步按照 CI/CD 最佳做法中的指导进行操作。
在开发和部署期间执行单元测试
问题
你想要在管道的开发和部署期间执行单元测试。
原因
在开发和部署周期中，可能需要在手动或自动发布管道之前对管道进行单元测试。 通过测试自动化，可以花更少的时间运行更多的测试，并保证可重复性。 在部署之前自动重新测试所有管道，可以为你提供一些保护，防止出现回归故障。 自动测试是 CI/CD 软件开发方法的一个关键组成部分：在 CI/CD 部署管道中加入自动测试，可显著提高质量。 从长远看，经过测试的管道工件可以重复使用，为你节省成本和时间。
解决方法
由于客户可能具有包含不同技能集的不同单元测试要求，因此通常的做法是执行以下步骤：
- 设置 Azure DevOps CI/CD 项目或开发 .NET/PYTHON/REST 类型 SDK 驱动的测试策略。
- 对于 CI/CD，创建包含所有脚本的生成工件，并在发布管道中部署资源。 对于 SDK 驱动的方法，使用 Python 中的 PyTest、C# 中的 Nunit（使用 .NET SDK）等工具开发测试单元。
- 将单元测试作为发布管道的一部分运行，或使用 ADF Python/PowerShell/.NET/REST SDK 独立运行。
例如，你想要删除文件中的重复项，然后将策展的文件存储为数据库中的一个表。 为了测试管道，可以使用 Azure DevOps 设置一个 CI/CD 项目。 你需要设置一个 TEST 管道阶段，在那里部署已开发的管道。 将 TEST 阶段配置为运行 Python 测试，以确保表数据符合预期。 如果没有使用 CI/CD，则请使用 Nunit 通过所需测试触发已部署的管道。 如果你对结果感到满意，可以最终将管道发布到生产实例。
在完成 CI/CD 部署或创作更新后管道运行发生暂时性失败
问题
在发生暂时性失败一段时间后，无需任何用户操作，新的管道运行就会开始成功。
原因
有多种情况可能会触发此行为，所有这些情况都涉及到旧的父资源版本调用了新的依赖资源版本。 例如，假设“执行管道”调用的现有子管道已更新为采用所需的参数，而现有父管道已更新为传递这些参数。 如果在父管道执行期间，但在“执行管道”活动发生之前进行部署，那么旧版本的管道会调用新版本的子管道，并且不会传递所需的参数。 这会导致管道失败并出现 UserError。 其他类型的依赖项也会发生这种情况，例如，如果在引用链接服务的管道运行执行期间对该服务进行了中断性变更。
解决方法
父管道的新运行将自动开始成功，因此通常不需要执行任何操作。 但是，为了防止这些错误，客户应在创作和规划部署时考虑到依赖项，以避免发生中断性变更。
无法参数化链接服务中的集成运行时
问题
需要参数化链接服务集成运行时
原因
不支持此功能。
解决方法
你需要手动选择并设置集成运行时。 也可以使用 PowerShell API 进行更改。 此更改可能会对下游产生影响。
在 CI/CD 期间更新/更改集成运行时。
问题
在 CI/CD 部署期间更改集成运行时名称。
原因
不支持参数化实体引用（链接服务中的集成运行时、活动中的数据集、数据集中的链接服务）。 在部署期间更改运行时名称会导致依赖的资源（引用集成运行时的资源）出现格式错误，引用无效。
解决方法
数据工厂要求你在 CI/CD 的所有阶段使用相同的集成运行时名称和类型。
ARM 模板部署失败，出现错误 DataFactoryPropertyUpdateNotSupported
问题
ARM 模板部署失败并出现错误，例如 DataFactoryPropertyUpdateNotSupported：不支持更新属性类型。
原因
ARM 模板部署正在尝试更改现有集成运行时的类型。 不允许此操作，它将导致部署失败，因为数据工厂需要在 CI/CD 的所有阶段使用具有相同名称和类型的集成运行时。
解决方法
若要在所有阶段中共享集成运行时，请考虑使用三元工厂，这只是为了包含共享的集成运行时。 可以在所有环境中将此共享工厂用作链接的集成运行时类型。 有关详细信息，请参阅持续集成和交付 - Azure 数据工厂
由于 PartialTempTemplates 文件的原因，GIT 发布可能失败
问题
如果在 PartialTemplates 文件夹中有 1000 个旧的临时 ARM 模板 JSON 文件，发布可能会失败。
原因
在发布时，ADF 会提取协作分支中每个文件夹内的每个文件。 过去，发布会在发布分支中生成如下两个文件夹：PartialArmTemplates 和 LinkedTemplates。 不再生成 PartialArmTemplates 文件。 然而，由于 PartialArmTemplates 文件夹中可能有许多旧文件（数千个），这可能会导致在发布时向 Github 发出许多请求，并达到速率限制。
解决方法
删除 PartialTemplates 文件夹并重新发布。 还可以删除该文件夹中的临时文件。
“在 ARM 模板中包括全局参数”选项不起作用
问题
如果使用旧的默认参数化模板，则从管理中心添加全局参数的新方法不起作用。
原因
默认参数化模板应包括全局参数列表中的所有值。
解决方法
- 使用更新的默认参数化模板一次性迁移到包括全局参数的新方法。 此模板引用全局参数列表中的所有值。 如果已重写发布管道中的模板参数，则还必须更新该管道中的部署任务。
- 如果已重写模板参数（全局参数），请更新 CI/CD 管道中的模板参数名称。
错误代码：InvalidTemplate
问题
消息内容为“无法分析表达式。”由于语法错误，未正确处理在某个活动的动态内容中传递的表达式。
原因
动态内容没有按照表达式语言要求来编写。
解决方法
- 对于调试运行，请检查当前 git 分支内管道中的表达式。
- 对于触发的运行，请在实时模式下检查管道中的表达式。
相关内容
有关故障排除的更多帮助，请尝试以下资源：