Dify工作流怎么调用外部API？HTTP请求、条件分支与结果检查指南

在 Dify 工作流中调用外部 API，关键不只是发出请求，还要确认输入如何映射、响应如何解析，以及失败时流程怎样处理。下面按一个公开查询接口的接入思路展开，不涉及知识库问答。示例中的接口地址、参数名和响应字段应以实际服务文档为准。

先明确请求要完成什么

假设工作流接收一个查询词，并把它传给公开查询接口，最后输出查询结果或人工处理提示。开始配置前，先从接口文档确认请求地址、HTTP 方法、必需参数、鉴权要求、响应格式和错误说明。不要凭字段名称猜测接口行为，也不要把真实密钥或敏感业务数据放进测试请求。

配置 HTTP 请求并映射变量

请求方法决定数据通常放在哪里：GET 请求常用 URL 查询参数传递筛选条件；POST 请求则可能使用请求体提交数据，具体要服从接口文档。URL 是目标地址，请求头用于传递内容类型、接受格式或接口要求的其他信息；查询参数和请求体不能混为一谈。

在请求配置中，把工作流开始节点的查询词映射到接口文档规定的参数位置。若文档要求 JSON 请求体，确保请求头与实际请求体格式相符；若接口只接受表单或其他格式，也应按其要求设置。变量映射后，检查必填值是否为空，数字、文本、布尔值和数组是否符合接口预期。不要仅因界面上能填入变量，就假定数据类型已经正确转换。

鉴权信息应使用当前 Dify 部署和版本支持的凭据或秘密变量机制；若当前环境没有相应能力，应按管理员提供的安全方式配置。不要把密钥写进提示词、普通文本变量、工作流输出或公开日志。

区分三类失败，再决定分支

• 网络或连接问题：例如域名无法解析、连接失败或请求超时。此时可能没有可供后续条件节点检查的正常响应体。
• HTTP 状态异常：请求到达服务端，但返回的状态码表示请求未成功。应结合接口文档判断状态码含义，不能把所有非成功响应都当成同一种情况。
• 业务字段报错：HTTP 请求可能成功，但响应中的业务状态、错误码或结果字段仍表示查询失败。判断这类情况需要检查响应体，而不只是看 HTTP 状态。

不同 Dify 版本、节点配置和执行路径对异常的处理可能不同。查看当前 HTTP 请求节点实际输出，并确认失败时条件分支是否有可用变量；如果节点在产生正常输出前就中止，就不能假设后续条件节点一定能读取状态码。按当前环境提供的异常处理方式设置失败路径，必要时让流程明确终止并返回可理解的提示。

解析返回值并设置条件分支

接口可能返回 JSON，也可能返回文本。先从节点运行记录确认响应体的实际类型和结构。如果响应已经是可访问的结构化数据，就按其字段路径取值；如果响应体是 JSON 文本，则使用工作流中可用的解析或代码处理步骤解析，再检查字段是否存在、类型是否符合预期。只有在接口字段明确为数字时，才按数字比较；不要把数字文本直接当作数值使用。

例如，可将查询结果是否为空作为业务分支条件：结果包含有效条目时，整理指定字段并输出；结果为空或缺少必要字段时，返回人工核对提示。条件应使用接口文档中真实存在的字段名，并同时考虑字段缺失和空值，避免把“没有结果”误判成“请求失败”。

用运行记录逐节点排查

1. 检查开始节点收到的查询词是否为空，以及类型是否符合预期。
2. 检查 HTTP 请求节点的实际请求参数、请求体和输出；核对敏感信息没有被打印到输出中。
3. 对照接口文档检查响应状态、响应体类型和关键业务字段。
4. 检查解析步骤与条件分支读取的变量路径是否一致，并分别测试有结果、空结果和异常情况。
5. 确认最终输出把有效信息与人工处理提示区分清楚。

调试时不要只看流程最终返回的文字。逐项查看各节点输入与输出，更容易定位问题发生在变量映射、网络请求、响应解析还是业务判断环节。