企业官网建设流程全解析

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/ToolJet

SOAP（Simple 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 数据源完全一致，有两种方式：

1. 在查询面板上点击+ Add new Data source按钮；
2. 通过 ToolJet 仪表盘导航到Data Sources页面（参见 overview.md），在侧边栏选择API类别下的REST API数据源。

Credentials（连接凭证）

在数据源配置表单中，需要填写以下连接信息（详见 configuration.md）：

Authentication（认证方式）

ToolJet 的 REST API 数据源支持以下认证类型（详见 authentication.md）：

• None：无需认证，适用于公开的测试 SOAP 服务；
• Basic：填写 Username 和 Password，适合大量企业 SOAP 服务使用的 HTTP Basic 认证；
• Bearer：填写 Token（通常是 JWT），在请求头中携带Authorization: Bearer <token>；
• OAuth 2.0：支持 Authorization Code 与 Client Credentials 两种授权模式，需要配置 Access Token URL、Client ID、Client Secret、Scope、Authorization URL 等参数。

SSL（安全套接层）

如果 SOAP 服务是 HTTPS 且使用私有 CA 或双向 TLS，需要在数据源中配置 SSL 证书（详见 configuration.md）：

• None：不做证书校验；
• 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 给出的操作步骤如下：

1. 点击编辑器底部面板查询管理器中的+ Add按钮；
2. 在 Data Source 部分选择REST API（即上一步创建的数据源）；
3. 将 Method 选择为POST，并填入 SOAP API 端点地址；
4. 添加请求头（Headers）：
   • Content-Type: text/xml——告知服务端请求体是 XML 报文；
   • 以及其他必需请求头（如Authorization、SOAPAction）；
5. 在 RequestBody中填写 XML 格式的 SOAP 报文；
6. 点击Preview预览查询返回的数据，或点击Run执行查询。

提示：查询结果还可以通过Transformations（数据转换）功能进一步加工处理。ToolJet 的转换器支持在查询返回后对数据进行格式化、筛选、聚合，适合将 SOAP 返回的 XML 响应进一步整理后再绑定到表格、下拉框等组件。

API 端点示例

官方文档使用了一个公共测试服务作为示例端点：

http://www.dneonline.com/calculator.asmx

这是一个提供Add、Subtract、Multiply、Divide等运算的 SOAP 计算器服务，非常适合用来验证你的 SOAP 查询配置是否生效。

请求体（Body）示例：SOAP Envelope

SOAP 请求体必须是合法的 SOAP Envelope 结构。以下是为Add操作（计算100 + 5）编写的完整报文示例（摘自 soapapi.md）：

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/"> <soapenv:Header/> <soapenv:Body> <tem:Add> <tem:intA>100</tem:intA> <tem:intB>5</tem:intB> </tem:Add> </soapenv:Body> </soapenv:Envelope>

解析一下这个报文的构成：

• soapenv:Envelope：SOAP 报文的最外层根元素，其命名空间固定为http://schemas.xmlsoap.org/soap/envelope/；
• xmlns:tem="http://tempuri.org/"：命名空间前缀tem对应目标服务的命名空间，需要与你对接的服务 WSDL 中定义的 targetNamespace 一致（tempuri.org是 ASP.NET Web Service 的默认命名空间）；
• soapenv:Header：SOAP 头，本示例为空；
• soapenv:Body：SOAP 体，内部<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.body，got客户端会将其逐字发送到服务端。这正是 SOAP XML 报文能够保持完整结构（缩进、标签、命名空间）不被 JSON 化破坏的原因。

与此同时，constructRequestBody（index.ts）展示了另一条值得注意的规则：GET 请求不会携带请求体（if (queryOptions.method === 'get') return undefined;）。这意味着如果你把 Method 误选为 GET，即使填了 XML 报文也不会被发送——这也是 SOAP 必须使用 POST 的底层原因之一。

附加说明与常见问题（Additional Notes）

官方文档 soapapi.md 特别强调以下三点，实际对接时务必注意：

1. SOAP API 通常使用 POST 方法。SOAP 规范基于 HTTP 的 POST 动词传递请求；改用其他方法（如 GET）会导致服务端无法识别请求，甚至直接报错；
2. 必须添加Content-Type: text/xml请求头。服务端依赖该请求头将请求识别为 SOAP 报文；缺失或误设为application/json时，服务端会因无法解析请求体而返回错误；
3. 如果 API 文档中指定了 SOAPAction，请务必添加该请求头。许多 SOAP 服务（尤其是基于 ASP.NET 的 Web Service）依赖SOAPAction头路由到具体操作，例如SOAPAction: "http://tempuri.org/Add"。SOAP 1.2 的某些实现也接受Content-Type: application/soap+xml，具体以服务 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 对接流程如下：

1. 进入Data Sources页面，选择REST API类型创建数据源；
2. 在Base URL填入 SOAP 服务端点（如http://www.dneonline.com/calculator.asmx）；
3. 按需配置认证（None / Basic / Bearer / OAuth 2.0）与 SSL 证书；
4. 在查询面板点击+ Add，选择该 REST API 数据源；
5. Method 选择POST，URL 填入端点地址（数据源已配置 Base URL 时也可留空）；
6. 添加Content-Type: text/xml请求头，必要时添加SOAPAction、Authorization；
7. Body 中粘贴从 WSDL 推导出的 SOAP Envelope 报文；
8. 点击Preview或Run验证结果；
9. 如需加工 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