ToolJet REST API 查询传参实战Raw JSON 与键值对两种动态值传递方式【免费下载链接】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本指南聚焦 ToolJet 中 REST API 查询的动态值传递讲解如何在请求体Body中通过Raw JSON与**键值对Key-Value Pairs**两种方式注入组件变量、文件数据等运行时值。读完本文你将掌握双花括号求值、模板字符串插值在 REST API 查询中的正确用法并结合源码理解这两种方式在 ToolJet 中的底层处理机制。为什么需要在 REST API 查询中传递值ToolJet 的应用构建器允许你将页面上的组件如表单输入框、文件上传器作为动态数据源注入到 REST API 查询的请求体中。典型场景包括将表单组件components.typeOfContentInput.value中的用户输入作为 API 请求内容将文件上传组件components.imageUploader.file[0].base64Data中的 Base64 编码图片数据随请求发送将下拉框、日期选择器等其他组件的值拼接到请求 JSON 中。REST API 查询编辑器在 Body 部分提供了两种传值模式Raw JSON原始 JSON 编辑与键值对输入。前者适合构建结构复杂的嵌套 JSON 请求体后者适合简单扁平参数。关于 REST API 数据源的完整连接与查询配置可参见 REST API 数据源文档。Raw JSON使用模板字符串注入动态值当 API 需要嵌套结构例如多层的contents→parts→inline_data时使用 Raw JSON 模式最直观。在查询编辑器的 Body 标签页中切换到Raw模式然后粘贴如下代码{{ { contents: [{ parts: [{ text: Generate the following content for this image in markdown format: content type: ${components.typeOfContentInput.value}, additional info: ${components.additionalInfoInput.value} }, { inline_data: { mime_type:image/jpeg, data: ${components.imageUploader.file[0].base64Data} } },], },], } }}语法拆解这段代码由三层语法叠加而成最外层双花括号{{ ... }}这是 ToolJet 的表达式求值语法用于在查询参数、请求体等任意字段中嵌入 JavaScript 表达式。编辑器会先对双花括号内的表达式求值再将结果作为实际发送的请求体。内层反引号模板字符串Template Literal反引号包裹的字符串支持${}插值语法即 JavaScript 的模板字符串特性。${components.typeOfContentInput.value}会在运行时被替换为对应组件的当前值。普通 JSON 文本模板字符串内部仍是标准 JSON 结构所有键名如contents、parts、mime_type保持原样仅需关注text、data等字段中嵌入的动态表达式。components.typeOfContentInput.value是 ToolJet 组件 API 的标准访问形式components.组件名.属性。文件上传组件FilePicker的file数组中的每个元素都包含name、type、base64Data等字段base64Data即文件内容的 Base64 编码字符串非常适合直接作为图片类 API 的输入。注意事项双花括号内是一个表达式因此最外层为{{与}}包裹内层字符串用反引号而非普通引号否则${}不会被解析若 JSON 值本身含有双花括号或反引号注意转义避免与 ToolJet 求值语法冲突Raw JSON 模式下编辑器默认将请求体作为 JSON 发送默认Content-Type: application/json。键值对直接使用双花括号求值对于结构扁平的请求体可以在 Body 标签页的键值对输入模式下逐行填写 Key 和 Value。此时 Value 字段直接用 ToolJet 最常见的双花括号求值方式引用组件值无需外层再套模板字符串普通常量直接输入例如gold动态值用{{ components.x.value }}引用组件属性字符串拼接可以直接将字符串与双花括号引用组合例如状态码字段status的值可以写为{{ a components.statusCode.value }}即把a这个字符串前缀与components.statusCode.value代表的动态数值拼接成一个完整字符串。双花括号内的任何 JavaScript 表达式都会被求值包括字符串拼接、三元运算、数组map等。键值对模式的使用要点键值对适合参数数量少、结构简单的请求体Raw JSON 适合嵌套复杂结构键和值均支持双花括号求值可用于动态构造参数名或参数值空值行会被自动过滤不会进入最终请求体见下文源码分析。源码视角两种传值方式的底层实现前端Body 标签页的 Raw 切换与编辑器ToolJet 的 REST API 查询编辑器位于 frontend/src/AppBuilder/QueryManager/QueryEditors/Restapi。在 index.jsx 中可以看到查询的默认配置项const options defaults( { ...props.options }, { headers: [], url_params: [], body: [], json_body: null, raw_body: null, body_toggle: false, cookies: [], } );其中body对应键值对列表raw_body对应 Raw JSON 模式下的原始字符串body_toggle则控制当前处于哪种模式。在 Tabs.jsx 中Body 标签页顶部有一个Raw开关切换该开关即改变bodyToggle的值开启后展示一个 300px 高的代码编辑器CodeHinter用于编写 Raw JSON 内容详见 TabContent.jsx。raw_body为空时会回退读取旧的json_body字段以保持向后兼容。后端请求体的构造与解析REST API 插件的请求执行逻辑在 plugins/packages/restapi/lib/index.ts。其中constructRequestBodyindex.ts对两种模式分别处理if (queryOptions[body_toggle]) { // FIXME: Remove json_body usage with data migration // For backward compatibility, check if JSON body was previously used queryOptions[raw_body] || queryOptions[json_body]; return queryOptions[raw_body]; } const _body (queryOptions.body || []).filter((o) { return o.some((e) !isEmpty(e)); }); // Body params of the source will be overridden by body params of the query if (!hasDataSource) return Object.fromEntries(_body); const bodyParams _body.concat(sourceOptions.body || []); return Object.fromEntries(bodyParams);可以清晰看到body_toggle为trueRaw 模式时直接取raw_body字符串作为请求体键值对模式下先过滤掉含空值的行isEmpty判断再把键值对数组转换为对象若使用了数据源请求体的参数还会与数据源级配置的 body 参数合并且查询级参数会覆盖数据源级同名参数。构造请求体后maybeParseJsonindex.ts会尝试用JSON5解析该字符串——JSON5 是 JSON 的超集允许注释、尾逗号、单引号等宽松语法对人工编写的 Raw JSON 更宽容。随后getContentTypeindex.ts依据请求头中的Content-Type决定发送方式默认application/json走requestOptions.json分支也支持application/x-www-form-urlencoded与multipart/form-data后者可识别带base64Data的文件对象并还原为二进制上传见 index.ts。这正好印证了上面示例中components.imageUploader.file[0].base64Data的用途——在 multipart 场景下它会被解析为真实文件内容。关于双花括号求值ToolJet 中所有可编辑字段包括键值对的 Key/Value、Raw JSON 内容都经过代码编辑器 CodeHinter 处理双花括号{{ }}内的内容按 JavaScript 表达式求值其余部分按普通字符串处理。这也是为什么键值对的 Value 中a与{{ ... }}可以无缝拼接——最终请求体里就是求值后的完整字符串。实战建议与常见问题优先用 Raw JSON 应对复杂嵌套涉及多级嵌套、数组结构如本文的contents/parts/inline_data时Raw JSON 可读性与可维护性远优于键值对注意字符串中的换行与引号模板字符串内可以包含换行如上例text字段的多行描述这是反引号语法的天然优势若改用普通字符串则需转义文件上传场景FilePicker 组件多选时可对components.imageUploader.file数组做遍历或按索引取单个文件如[0]每个文件对象含name、type、base64Data字段Base64 数据可直接用于图片生成、OCR、语音转写等 AI 类 API查询结果的使用REST API 返回的 JSON 可通过{{ queries.queryname.data }}加载到表格、列表视图等组件返回图片等二进制内容时得到 Base64 字符串可参考 REST API 数据源文档 中的响应类型说明区分求值时机双花括号表达式在查询执行时求值因此组件值变化后需要重新运行查询或开启应用加载时运行查询才能拿到最新值。掌握 Raw JSON 的模板字符串插值与键值对的双花括号求值即可在 ToolJet 中灵活构建携带动态上下文的 REST API 请求——无论是向 Gemini 类多模态 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考