有数数据填报提交数据技能

功能

该技能允许用户向有数BI数据填报表单提交一条数据，无需在平台中手动操作。

使用场景

当用户想要向某个数据填报表单提交一条数据时
已通过 youdata-survey-meta-query 获取到表单元数据（formTemplate），需要按格式构造数据并提交
用户已有一份符合格式要求的提交数据，直接调用脚本提交

依赖环境

Node.js 20+
需要网络连接访问有数平台API
需要安装 skill youdata-env-config 并完成配置

配置要求

需要在skill目录下 /scripts/env.js 中配置：

tokenKey: 用户的有数tokenKey
domainUrl: API域名

调用示例

step1：使用 skill youdata-env-config 获取 env（json字符串格式），同一次会话youdata系列的skill可以复用，不用二次生成
step2：获取当前 SKILL.md 的绝对目录地址 skillFolder
step3：构造提交数据 submitData（JSON字符串格式，见下方参数说明）
step4：调用脚本

node ${skillFolder}/scripts/index.js <submitData> <env>

参数说明

submitData（JSON字符串）

提交数据对象，包含以下字段：

字段	类型	是否必填	说明
`surveyId`	string	✅ 必填	数据填报的唯一标识符
`schemaHash`	string	可选	当前填报的 hash 值，可从 `youdata-survey-meta-query` 返回的 `formTemplate.schemaHash` 中获取
`datas`	array	✅ 必填	提交数据二维数组：外层数组每项代表一条提交记录，内层数组为该条记录中各表单项的填写内容，见下方说明

datas 数组项结构

datas 是一个二维数组（Array<Array<object>>）：

外层数组：每项代表一条完整的提交记录，当前一次提交仅包含一条记录，即 datas 长度为 1
内层数组：每项为一个表单字段对象，对应表单中的一个填写项

内层数组中每个对象的结构如下：

字段	类型	是否必填	说明
`id`	string	id / name 至少提供一个	表单项的唯一标识，来自 `formTemplate.datas[][].id`，匹配优先级高于 name
`name`	string	id / name 至少提供一个	表单项名称，来自 `formTemplate.datas[][].name`
`value`	any	普通字段必填	填写的值，格式根据字段类型而定（子表单字段不使用此字段）
`structure`	array	子表单字段必填	仅子表单类型使用，描述子表单内部的表单项，见下方子表单说明

各字段类型的 value 格式

字段类型	value 类型	示例
数字	string（字符串形式的数值）	`"123"`
文本	string	`"示例文本"`
日期	string，格式 `YYYY-MM-DD` 或 `YYYY-MM-DD HH:mm:ss`	`"2026-04-10"`
单选	array，含一个字符串	`["选项1"]`
多选	array，含多个字符串	`["选项1", "选项2"]`
邮箱	string	`"example@gmail.com"`
手机	string	`"13800138000"`
电话	string	`"7867898"`
性别	string	`"男性"` / `"女性"`
附件	string，空时为 `""`	`""`
子表单	不使用 value，使用 `structure` 字段	见下方

子表单字段说明

子表单字段不使用 value，而是使用 structure 数组来描述子表单内部的表单项。structure 中每项代表子表单内的一个表单项，结构与外层 datas 数组项相同，包含：

字段	类型	是否必填	说明
`id`	string	id / name 至少提供一个	子表单项的唯一标识，匹配优先级高于 name
`name`	string	id / name 至少提供一个	子表单项名称
`value`	any	✅ 必填	子表单项的填写值，格式规则与外层表单项一致

示例（子表单内包含两个表单项）：

{
    "name": "子表单",
    "structure": [
        {
            "id": "d770b0e2_19f9_fe18_7a19_413d913f7833",
            "name": "数字",
            "value": "0.120"
        },
        {
            "name": "子表单内文本",
            "value": "示例文本"
        }
    ]
}

提交数据示例

以下是一个完整的 submitData 示例（对应 surveyId 为 6111 的表单）：

{
    "surveyId": "6111",
    "schemaHash": "0acc84de5624c1d9553813d5696b70c5",
    "datas": [[
        {
            "name": "数字",
            "value": "123"
        },
        {
            "id": "p0c0ef05_60bb_e070_f027_93eb55e7fce9",
            "value": "wenben"
        },
        {
            "id": "q451a27c_d983_5b04_d11b_e8fcc2d2d0b1",
            "value": "2026-04-10"
        },
        {
            "id": "d57aa42d_d553_1399_50fe_e8d8309b98d5",
            "value": ["选项1"]
        },
        {
            "id": "g8cf7228_09c5_4fdc_3165_b202b74e3aea",
            "value": ["选项1", "选项2"]
        },
        {
            "id": "y6e23d47_9927_adcf_5000_c35f166242d6",
            "value": "whl1234@gmail.com"
        },
        {
            "id": "cdb52c2b_d485_3f7a_3b3a_0c36a4d86162",
            "value": "13765546678"
        },
        {
            "id": "p1b0914c_1690_4c23_89b7_00c3b8ad5d3b",
            "value": "7867898"
        },
        {
            "id": "n9254ef6_9a29_b437_76ce_feb878dda10a",
            "value": "女性"
        },
        {
            "name": "子表单",
            "structure": [
                {
                    "id": "d770b0e2_19f9_fe18_7a19_413d913f7833",
                    "name": "数字",
                    "value": "0.120"
                }
            ]
        }
    ]]
}

返回结果

返回JSON格式的提交结果：

{
    "code": 200,      // 是否提交成功
    "result": "47099"  // 填报ID
}

错误处理

缺少参数时会提示正确用法
配置不完整时会提示配置信息
网络错误会显示具体错误信息
脚本提交失败时显示错误信息并立刻终止问答

youdata-survey-submit-data