ToolJet 中通过 REST API 数据源调用 SOAP API 的完整实战指南【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJetSOAPSimple Object Access Protocol至今仍广泛存在于银行、物流、ERP 等企业级系统中。ToolJet 本身并未内置独立的 SOAP 数据源类型而是利用其成熟的REST API 集成来承载 SOAP 请求——因为 SOAP over HTTP 本质上是使用 HTTP 传输 XML 报文这与 REST API 的请求/响应模型天然兼容。本文将基于 ToolJet 开源仓库中的官方文档 soapapi.md 及其底层 REST API 插件源码完整讲解如何在 ToolJet 中创建 SOAP API 数据源、构造 SOAP Envelope 报文、配置认证与请求头并深入剖析底层请求分发机制帮助你顺利对接任意 SOAP Web Service。读完本文你将掌握在 ToolJet 编辑器中添加基于 REST API 的 SOAP 数据源、编写可运行的 SOAP 查询含完整 XML 报文示例、正确设置Content-Type与SOAPAction请求头以及理解请求体在插件源码层是如何根据 Content-Type 被序列化发送的。SOAP API 与 REST API 数据源的关系ToolJet 官方的 SOAP API 文档明确说明ToolJet 通过 REST API 集成来建立与 SOAP API 的连接即 SOAP API 数据源在 ToolJet 中并不需要单独的插件类型而是复用 REST API 数据源的全部能力参见 soapapi.md 与 REST API 配置文档。这样做的好处是显而易见的你不需要为 SOAP 单独维护一套连接配置体系REST API 数据源已有的Headers、URL Parameters、Body、Cookies、认证方式None / Basic / Bearer / OAuth 2.0、SSL 证书等能力全部可以直接复用底层请求发送、响应解析、错误处理、网络重试等逻辑由统一的 REST API 查询服务RestapiQueryService承担行为可预期、可调试你可以在一个数据源实例下同时管理 JSON 风格接口与 SOAP XML 接口的查询减少数据源数量。从源码层面看REST API 查询服务的实现位于 plugins/packages/restapi/lib/index.ts。该服务基于gotHTTP 客户端发送请求并在发出请求前执行 SSRF 防护校验validateUrlForSSRF与请求选项构造constructValidatedRequestOptions。SOAP 请求正是经由这条统一的执行链路完成的。第一步创建 SOAP API 数据源即 REST API 数据源由于 ToolJet 使用 REST API 配置来处理 SOAP API创建数据源的入口与创建普通 REST API 数据源完全一致有两种方式在查询面板上点击 Add new Data source按钮通过 ToolJet 仪表盘导航到Data Sources页面参见 overview.md在侧边栏选择API类别下的REST API数据源。Credentials连接凭证在数据源配置表单中需要填写以下连接信息详见 configuration.md配置项说明SOAP 场景下的建议Base URLAPI 服务的网络地址即 SOAP 服务的 WSDL 中soap:address location...指向的端点地址填写 SOAP 服务端点如http://www.dneonline.com/calculator.asmxHeaders随每个请求发送的键值对请求头可把SOAPAction、Authorization等公共请求头放在此处对使用该数据源的所有查询生效URL Parameters随每个请求发送的 URL 查询参数一般 SOAP 服务用不到留空即可Body请求体键值对SOAP 报文体应在查询级编写数据源级一般留空Cookies随请求发送的 Cookie会附加到使用该数据源的每个查询上如服务端依赖会话 Cookie 可配置于此Authentication认证方式ToolJet 的 REST API 数据源支持以下认证类型详见 authentication.mdNone无需认证适用于公开的测试 SOAP 服务Basic填写 Username 和 Password适合大量企业 SOAP 服务使用的 HTTP Basic 认证Bearer填写 Token通常是 JWT在请求头中携带Authorization: Bearer tokenOAuth 2.0支持 Authorization Code 与 Client Credentials 两种授权模式需要配置 Access Token URL、Client ID、Client Secret、Scope、Authorization URL 等参数。SSL安全套接层如果 SOAP 服务是 HTTPS 且使用私有 CA 或双向 TLS需要在数据源中配置 SSL 证书详见 configuration.mdNone不做证书校验CA Certificate粘贴 CA 证书内容用于校验服务端证书Client Certificate需要同时提供 Client Key、Client Cert 与 CA Cert用于客户端证书认证。从源码 index.ts 可以看到这三种模式分别对应got的https.certificateAuthority、https.key、https.certificate选项并且NODE_EXTRA_CA_CERTS环境变量中的额外根证书也会被合并进信任链。第二步在查询管理器中编写 SOAP 查询数据源创建完成后即可编写查询与 SOAP API 交互。官方文档 soapapi.md 给出的操作步骤如下点击编辑器底部面板查询管理器中的 Add按钮在 Data Source 部分选择REST API即上一步创建的数据源将 Method 选择为POST并填入 SOAP API 端点地址添加请求头HeadersContent-Type: text/xml——告知服务端请求体是 XML 报文以及其他必需请求头如Authorization、SOAPAction在 RequestBody中填写 XML 格式的 SOAP 报文点击Preview预览查询返回的数据或点击Run执行查询。提示查询结果还可以通过Transformations数据转换功能进一步加工处理。ToolJet 的转换器支持在查询返回后对数据进行格式化、筛选、聚合适合将 SOAP 返回的 XML 响应进一步整理后再绑定到表格、下拉框等组件。API 端点示例官方文档使用了一个公共测试服务作为示例端点http://www.dneonline.com/calculator.asmx这是一个提供Add、Subtract、Multiply、Divide等运算的 SOAP 计算器服务非常适合用来验证你的 SOAP 查询配置是否生效。请求体Body示例SOAP EnvelopeSOAP 请求体必须是合法的 SOAP Envelope 结构。以下是为Add操作计算100 5编写的完整报文示例摘自 soapapi.mdsoapenv:Envelope xmlns:soapenvhttp://schemas.xmlsoap.org/soap/envelope/ xmlns:temhttp://tempuri.org/ soapenv:Header/ soapenv:Body tem:Add tem:intA100/tem:intA tem:intB5/tem:intB /tem:Add /soapenv:Body /soapenv:Envelope解析一下这个报文的构成soapenv:EnvelopeSOAP 报文的最外层根元素其命名空间固定为http://schemas.xmlsoap.org/soap/envelope/xmlns:temhttp://tempuri.org/命名空间前缀tem对应目标服务的命名空间需要与你对接的服务 WSDL 中定义的 targetNamespace 一致tempuri.org是 ASP.NET Web Service 的默认命名空间soapenv:HeaderSOAP 头本示例为空soapenv:BodySOAP 体内部tem:Add是调用的操作名tem:intA与tem:intB是该操作的两个入参。不同 SOAP 服务的操作名、命名空间与参数结构各不相同实际对接时请以目标服务 WSDL 中wsdl:operation与wsdl:message的定义为准。底层机制Content-Type 如何决定请求体的发送方式为什么设置Content-Type: text/xml之后XML 报文就能被正确发送这可以从 REST API 插件的请求体构造逻辑中找到答案。在 plugins/packages/restapi/lib/index.ts 中addBodyToRequest方法会读取请求头中的Content-Type并根据其值选择不同的序列化方式switch (contentType) { case application/json: requestOptions.json this.maybeParseJson(body); break; case application/x-www-form-urlencoded: this.setFormUrlencodedBody(requestOptions, body); break; case multipart/form-data: this.setMultipartFormDataBody(requestOptions, body); break; default: requestOptions.body body; // text/xml 及其他类型走这里原样字符串发送 }当请求头为text/xml或其他非 JSON 类型时代码走default分支将请求体作为原始字符串原样放入requestOptions.bodygot客户端会将其逐字发送到服务端。这正是 SOAP XML 报文能够保持完整结构缩进、标签、命名空间不被 JSON 化破坏的原因。与此同时constructRequestBodyindex.ts展示了另一条值得注意的规则GET 请求不会携带请求体if (queryOptions.method get) return undefined;。这意味着如果你把 Method 误选为 GET即使填了 XML 报文也不会被发送——这也是 SOAP 必须使用 POST 的底层原因之一。附加说明与常见问题Additional Notes官方文档 soapapi.md 特别强调以下三点实际对接时务必注意SOAP API 通常使用 POST 方法。SOAP 规范基于 HTTP 的 POST 动词传递请求改用其他方法如 GET会导致服务端无法识别请求甚至直接报错必须添加Content-Type: text/xml请求头。服务端依赖该请求头将请求识别为 SOAP 报文缺失或误设为application/json时服务端会因无法解析请求体而返回错误如果 API 文档中指定了 SOAPAction请务必添加该请求头。许多 SOAP 服务尤其是基于 ASP.NET 的 Web Service依赖SOAPAction头路由到具体操作例如SOAPAction: http://tempuri.org/Add。SOAP 1.2 的某些实现也接受Content-Type: application/soapxml具体以服务 WSDL 为准。响应处理SOAP 服务的响应同样是 XML 格式。ToolJet 的 REST API 查询服务在收到响应后会进行如下处理见 index.ts 的getResponse方法若响应体是合法 JSON则解析为 JSON 对象若响应content-type表明是二进制数据image/前缀等则转换为 Base64 字符串其余情况包括 SOAP 的 XML 响应原样返回响应文本。因此SOAP 查询的结果可以在后续组件中通过{{queries.queryname.data}}引用配合Transformations将 XML 文本解析、抽取所需字段后再绑定到组件是推荐的做法。网络错误重试对于稳定性要求较高的企业 SOAP 服务可以利用 REST API 查询的Retry on network errors能力默认开启最多重试 3 次覆盖 HTTP 408/413/429/500/502/503/504/521/522/524 状态码以及ETIMEDOUT、ECONNRESET、ECONNREFUSED、ENOTFOUND等网络错误。该配置可在数据源级设置默认行为也可在单个查询的Settings选项卡中覆盖详见 querying-rest-api.md。完整操作流程总结把上面所有内容串起来一个完整的 SOAP API 对接流程如下进入Data Sources页面选择REST API类型创建数据源在Base URL填入 SOAP 服务端点如http://www.dneonline.com/calculator.asmx按需配置认证None / Basic / Bearer / OAuth 2.0与 SSL 证书在查询面板点击 Add选择该 REST API 数据源Method 选择POSTURL 填入端点地址数据源已配置 Base URL 时也可留空添加Content-Type: text/xml请求头必要时添加SOAPAction、AuthorizationBody 中粘贴从 WSDL 推导出的 SOAP Envelope 报文点击Preview或Run验证结果如需加工 XML 响应启用Transformations或在前端组件中使用{{queries.queryname.data}}结合 JS 方法处理。通过这条路径ToolJet 可以对接任意标准 SOAP Web Service——无论是内部的 ERP/CRM 接口还是公网测试服务。理解SOAP 请求 POST XML 报文 正确请求头这一本质再结合本文梳理的数据源配置、报文结构与底层请求分发机制你就能在 ToolJet 中稳定、高效地集成 SOAP 生态。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考