CSV转JSON和数组

CSV转JSON和数组 用于从指定 URL 下载 CSV 文件，并解析为 JSON 字符串或对象数组格式，支持自定义分隔符、编码和注释标记符，适用于数据导入和格式转换场景。

指令标识：CSVParser
指令类型：数据处理指令
指令描述：从指定 URL 下载 CSV 文件并解析为 JSON 字符串或对象数组格式

先选使用方式

工作流支持「可视化编排」和「代码编排」两种创建方式。CSV转JSON和数组 在两种方式里都能用，核心业务参数一致。

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

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

什么时候用？

• 需要从远程 CSV 文件导入数据到系统。
• 需要把 CSV 格式转换为 JSON 字符串或对象数组。
• 需要处理报表导出的 CSV 数据。
• 需要集成不同系统的 CSV 数据源、做批量数据导入。

使用前确认

• CSV 文件 URL 必填，且地址可访问、返回有效数据。
• 明确处理方式：JSON_STRING（JSON 字符串）或 ARRAY（二维数组）。
• 文件编码与分隔符已知，必要时通过高级选项设置 encode、delimiter。
• 大文件解析时注意内存使用和处理时间。

可视化编排：从 0 到跑通

下面用一个常见场景演示：下载一个用户清单 CSV 并解析为对象数组，供后续遍历使用。按 4 步即可跑起来：

1. 在工作流画布中添加 CSV转JSON和数组 节点。
2. 在 CSV文件URL 中填写文件地址，例如：

https://data.example.com/users.csv

3. 在 处理方式 中选择 ARRAY（二维数组）。
4. 点击运行，在输出变量中查看解析结果。

示例输入 CSV：

name,email,age,city
张三,zhangsan@example.com,30,城市A
李四,lisi@example.com,25,城市B
王五,wangwu@example.com,28,城市C

示例输出结果（ARRAY）：

{
  "fileName": "users.csv",
  "headers": ["name", "email", "age", "city"],
  "totalRows": 3,
  "data": [
    {"name": "张三", "email": "zhangsan@example.com", "age": "30", "city": "城市A"},
    {"name": "李四", "email": "lisi@example.com", "age": "25", "city": "城市B"},
    {"name": "王五", "email": "wangwu@example.com", "age": "28", "city": "城市C"}
  ]
}

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
CSV文件URL	fileUrl	String	是	-	CSV 文件的 URL 地址
处理方式	type	Enum	是	-	处理方式：JSON_STRING（JSON 字符串）、ARRAY（二维数组）
列分隔符	delimiter	String	否	-	高级选项。列分隔符，留空时按系统默认处理
编码格式	encode	String	否	-	高级选项。文件编码格式，留空时按系统默认处理
注释标记符	commentChar	String	否	-	高级选项。注释标记符，匹配的行会被跳过，留空时按系统默认处理
是否发送消息	sendMsgFlag	Boolean	否	true	是否发送节点消息

输出参数

界面名称	代码属性名	类型	必填	说明
输出内容	outKey	JSON	否	解析结果输出变量名，包含 fileName、headers、totalRows、data 等字段

成功标准

• 运行日志中节点为成功状态，没有网络或解析错误。
• 输出变量中包含解析后的 data（JSON_STRING 为字符串，ARRAY 为对象数组）。
• headers 与 totalRows 与源 CSV 文件一致。

失败排查

该节点失败处理默认为「报错中止」（stop）。

现象 / 报错原文	可能原因	处理建议
下载失败 / 网络超时	CSV 文件 URL 不可访问	在浏览器中验证 URL 可访问，确认文件存在
解析出现乱码	文件编码与默认不一致	通过 encode 设置正确的编码（如 UTF-8）
字段未按预期拆分	分隔符与文件实际不符	通过 delimiter 设置实际分隔符（如 ;）
注释行被当作数据	未设置注释标记符	通过 commentChar 设置注释标记符（如 #）
处理结果类型不对	处理方式选择错误	确认 type 选择了 JSON_STRING 或 ARRAY

Python 代码编排

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

# 解析为 JSON 字符串
bots.csvParser(
    fileUrl="https://data.example.com/users.csv",
    type="JSON_STRING",
    outKey="parsedData",
)

解析为对象数组，并自定义分隔符和编码：

bots.csvParser(
    fileUrl="https://data.example.com/users_semicolon.csv",
    type="ARRAY",
    delimiter=";",
    encode="UTF-8",
    outKey="users",
)

处理带注释的 CSV，跳过以 # 开头的行：

bots.csvParser(
    fileUrl="https://data.example.com/commented_data.csv",
    type="ARRAY",
    commentChar="#",
    outKey="cleanData",
)

可视化表单里的「CSV文件URL」「处理方式」「列分隔符」「编码格式」「注释标记符」「输出内容」分别对应代码里的 fileUrl、type、delimiter、encode、commentChar、outKey。

如果你想在工作流中通过节点动态编排该指令，可使用 执行指令（XML）节点，按上方参数表进行配置。

常见问题

Q1：JSON_STRING 和 ARRAY 有什么区别？

A： JSON_STRING 的 data 字段是一段 JSON 字符串，需要再次反序列化后使用；ARRAY 的 data 字段是可直接遍历的对象数组。

Q2：如何处理不同编码的 CSV？

A： 通过高级选项 encode 指定文件实际编码（如 UTF-8），避免出现乱码。

Q3：注释行和空行会被处理吗？

A： 设置 commentChar 后，匹配的注释行会被自动跳过；空行同样会被忽略。

相关指令

• CSV 转 JSON
• JSON 转 CSV
• Excel 解析
• JSON 转 Excel