JSON 和数组转 Excel

JSON 和数组转 Excel 用于将 JSON 数组或二维数组转换为 Excel 格式文件，并自动上传至云存储，返回文件的访问地址。它常用于数据导出、报表生成与系统集成等场景。

指令标识：ExcelExporter
指令类型：数据处理指令
指令描述：将 JSON 数组或二维数组转换为 Excel 文件并上传至云存储

先选使用方式

工作流支持「可视化编排」和「代码编排」两种创建方式。JSON 和数组转 Excel 在两种方式里都能用，核心业务参数一致，区别主要是你通过界面配置，还是通过 Python 脚本配置。

方式	怎么用	适合人群
可视化编排（推荐先学）	拖入「JSON 和数组转 Excel」节点，填写输入数据并选择处理方式	大多数用户，零代码，适合快速搭建和调试
代码编排（Python）	在脚本中调用 `bots.excelExporter(input_Str="...", outKey="output")`	熟悉代码、需要复用脚本或批量生成流程的用户

第一次使用建议先用可视化编排跑通，再迁移到 Python 代码编排。下方「参数说明」同时给出界面字段和代码参数名，方便两种方式对应。

什么时候用？

需要把系统中的结构化数据导出为 Excel 格式，便于归档和备份。
需要把查询结果或统计数据转换为 Excel 报表。
需要在不同系统间进行数据格式转换，便于系统迁移或第三方对接。

使用前确认

输入数据为有效的 JSON 数组或二维数组格式。
已明确处理方式：JSON_STRING（JSON 字符串）或 ARRAY（二维数组）。
已规划好用于保存返回地址的输出变量名。

可视化编排：从 0 到跑通

下面用一个常见场景演示：把一组用户数据导出为 Excel。按 3 步即可跑起来：

在工作流画布中添加 JSON 和数组转 Excel 指令。
在右侧配置面板填写输入数据并选择处理方式（JSON_STRING）：

[
  {"姓名": "王平", "userid": "10000", "性别": "男"},
  {"姓名": "李娜", "userid": "10001", "性别": "女"}
]

在 将结果保存至 填写变量名（例如 output），点击运行获取返回的文件地址。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
输入数据	`input_Str`	String	是	-	需要转换的 JSON 数组或二维数组数据，支持复杂嵌套结构
处理方式	-	Enum	是	JSON_STRING	数据处理方式：`JSON_STRING`（JSON 字符串）、`ARRAY`（二维数组）
是否包含表头	`includeHeader`	Boolean	否	-	是否在首行输出表头（JSON 数组格式通常为 `true`，二维数组按需设置）
是否发送消息	`sendMsgFlag`	Boolean	否	false	转换完成后是否发送通知消息

输出参数

界面名称	代码属性名	类型	必填	说明
将结果保存至	`outKey`	String	否	保存生成的 Excel 文件云存储访问地址的变量名（默认 `output`）

成功标准

运行日志中没有数据格式或上传相关错误。
输出变量中保存了 Excel 文件的访问地址（而非文件内容本身）。
下载该地址可得到内容正确的 Excel 文件。

输出结果示例：

生成的 Excel 内容（JSON 数组格式）：

姓名	userid	性别
王平	10000	男
李娜	10001	女

返回的访问地址示例：

https://example.com/assets/bucket-name/excel-files/user-data-20241201-123456.xlsx

失败排查

现象 / 报错原文	可能原因	处理建议
报数据格式错误	输入不是有效的 JSON 数组或二维数组	校验输入数据结构，确认与「处理方式」匹配
嵌套字段变成字符串	数据中包含嵌套对象或数组	嵌套结构会被转为字符串保存，按需提前展开
列顺序与预期不符	列顺序基于首个对象的键顺序	保证首个对象字段顺序与预期一致
拿到的是地址不是文件	输出为云存储访问地址	通过该地址下载 Excel 文件

Python 代码编排

代码编排以 Python 为主。运行上下文由代码编排模板创建，示例里只需要关注业务指令本身。

# JSON 数组转 Excel，结果保存到 output
bots.excelExporter(
    input_Str='[{"姓名":"王平","userid":"10000","性别":"男"},{"姓名":"李娜","userid":"10001","性别":"女"}]',
    includeHeader=True,
    sendMsgFlag=False,
    outKey="output",
)

二维数组转 Excel（通常不带表头）：

bots.excelExporter(
    input_Str='[["苹果","红色",3.5],["香蕉","黄色",2.0],["樱桃","红色",6.0]]',
    includeHeader=False,
    sendMsgFlag=False,
    outKey="output",
)

可视化表单里的「输入数据」「是否包含表头」「是否发送消息」「将结果保存至」分别对应代码里的 input_Str、includeHeader、sendMsgFlag、outKey。

如果你想在工作流中通过节点动态编排指令，可使用执行指令（XML）节点。

常见问题

Q1：输入数据需要满足什么条件？

A：输入数据必须是有效的 JSON 数组或二维数组格式，运行前建议校验数据结构的完整性和正确性。

Q2：嵌套结构如何处理？

A：当 JSON 对象中包含嵌套对象或数组时，会被转换为字符串形式保存在 Excel 中，建议根据需求提前处理嵌套结构。

Q3：输出变量保存的是文件还是地址？

A：生成的 Excel 文件会自动上传至云存储，输出变量保存的是文件访问地址，不是文件内容本身。