Dify 企业级实验12外部系统集成——第三方系统如何通过 Dify API 双向编排Dify 实验系列 · 企业级 12/12 | 实验编号DIFY-104-12基于 Dify 1.16.1 实测2026-081. 业务场景先讲一个我们实际遇到的场景。项目交付给客户不是给一个网页而是给一套可编程的 API 一套能主动干活的工作流。客户 OA 里点「智能问答」按钮调用 Dify 工作流返回答案另一边Dify 工作流要主动查 OA 的审批数据。双向打通Dify 才能真正嵌进客户现有系统——被调时是能力中台主动时是执行者。我们第一次接这类需求时第一反应也是「集成嘛给个链接让客户自己调」。真正动手才发现——只给链接等于没交付外部系统调不进来、Dify 也调不出去两头不通集成就是半吊子。这不是个例。任何「把 Dify 嵌进客户现有系统」的交付都是这个模式外部系统调 DifyService API Dify 调外部系统HTTP/工具两头都要通。2. 场景痛点这个流程的痛点在交付方和客户对接人身上体现得最直接交付物是网页客户系统嵌不进去用户在两个系统之间来回切体验割裂。单向集成只会被调、不会主动调OA 里的数据进不来工作流成了孤岛。鉴权混乱一个 Key 通吃所有能力泄露即全量风险token 过期不刷新链路说断就断。外部不可达无兜底OA 系统挂了整个工作流跟着 failed主流程被拖垮。本质上集成不是「给个链接」是「双向可编程」——被调方要有干净的 API主动方要有降级的能力。3. 方案为什么是Service API HTTP 双向集成Dify 的 Service API HTTP 节点headers 模板 fail-branch正好实现双向集成。选它的理由被调方开箱即用工作流发布后创建 API Key外部系统直接调 Service API每个外部系统独立 Key主动方动态鉴权http 节点 headers 支持模板语法动态带 token模拟登录→带 token 调用成标准链路降级兜底error_strategy: fail-branch cd_fallback外部不可达不拖垮主流程。这篇文章我们就用它搭一套「OA 双向集成」知识问答被调方 主动查询主动方。4. 整体架构两个应用被调方知识问答 主动方主动查询。主动方主动查询Dify 调 OAokfalse开始query/tokencd_token模拟登录取访问令牌http_oaGET OA 接口Authorization: Bearer tokencd_parse解析响应成功/失败if5OA 是否正常end_ok输出查询结果cd_fallback降级提示end_fail被调方知识问答Dify 被 OA 调用开始questioncd_src按问题关键词生成引用来源如退货 → 《售后政策》第 2 章lm生成回答引用来源编号结束输出 answer/sources链路很清晰被调方——OA 调 Service API 拿 answer/sources主动方——模拟登录取 token → 带 token 调 OA → 成功输出 / 失败降级。两头都留好接口与降级是双向集成的关键设计。5. 模块设计5.1 被调方Service API 暴露工作流发布后创建 API Key给 OA 开发者的调用文档交付物之一POST /v1/workflows/run Authorization: Bearer app-xxxxxxxx# 每个外部系统独立 Key{inputs:{question:如何申请退货},response_mode:blocking,user:oa-1001}# 响应 data.outputs: {answer: ..., sources: ...}LLM 节点 system 提示词要求「基于知识回答问题引用来源以编号形式标注知识库没有的内容直接说明未找到不要编造」。5.2 主动方登录取 tokencd_token 模拟登录生产换真实登录接口输出 token 供 http 节点引用defmain(token:str)-dict:return{token:tokenormock-oa-token-abc123}5.3 调 OAheaders 模板引用http 节点 headers 支持模板语法动态带 token实测要点url:http://172.19.0.50:8123/echo?q{{#start.query#}}method:GETheaders:Authorization: Bearer {{#cd_token.token#}}timeout:{connect:10,read:60,write:20}error_strategy:fail-branch5.4 响应解析与降级cd_parse 解析回显的查询词与 Authorization 头查询词为空或解析失败 → successfalse → cd_fallback 降级提示# cd_parse节选datajson.loads(bodyor{})qdata.get(args,{}).get(q,)oktrueifqelsefalsedetailOA 接口返回查询词「str(q)」Authorizationstr(data.get(headers,{}).get(Authorization,无))return{success:ok,data:detail,raw:str(bodyor)[:300]}# cd_fallbackreturn{message:OA 系统暂时不可用请稍后重试。查询词「str(queryor)」已记录恢复后自动补查。}6. 运行验证输入预期实测OA 调 Dify带 Key问题如何申请退货返回 answer sources《售后政策》第 2 章等与预期一致Service API 返回 data.outputsDify 调 OAquery审批单 A2024回显查询词与 Authorization 头走 end_ok与预期一致输出 OA 回显明细Key 无效401错误码明确文档含错误码表与预期一致查询词为空cd_parse 判定失败 → 降级提示与预期一致提示「OA 系统暂时不可用…」OA 不可达工作流不整体失败走降级分支与预期一致error_strategy: fail-branch7. 实战坑坑现象修复API Key 权限过大一个 Key 通吃所有能力泄露即全量风险每个外部系统独立 Key 独立授权102/103 Key 管理实测外部 API token 过期未刷新调用突然 401链路中断统一「登录取 token → 带 token 调用」链路token 存 KV 供刷新102-10 实测http 节点不会自动带鉴权头OA 接口返回未授权headers 用模板引用动态注入Authorization: Bearer {{#cd_token.token#}}实测外部系统不可达无降级节点报错工作流整体失败error_strategy: fail-branch cd_fallback 降级提示102-17 实测无接口文档外部开发对接全靠猜反复返工交付「请求/响应/错误码」调用文档实验文档设计约束8. 实验文档及源码获取实验文档完整操作步骤含 OA 对接文档样例DIFY-104-12外部系统集成——第三方系统通过Dify API双向编排.md源码一被调方dify104_12_01_知识问答.yml源码二主动方dify104_12_02_主动查询.yml源码目录dify-104/dsl文章聚焦核心配置与采坑点实验的完整分步操作节点搭建/参数表/调试指引见实验文档原文。下一篇系统可靠性系列 你在这个实验的场景里踩过什么坑欢迎评论区分享你的实战经验。