云控脚本函数详解：ecloud 云端调度的 API 全清单

云控平台的脚本，和单机脚本最大的区别是：数据在云端、任务在云端、状态在云端。单机脚本只管“跑完这一遍”，云控脚本要回答“我是谁、跑哪个任务、参数是什么、数据放哪”。

这些能力都封装在 ecloud 脚本函数里——脚本内直接调用，无需对接接口。这篇文章把 ecloud 函数按类别过一遍，附实例代码。

一、云控脚本函数是什么

云控平台对应的脚本函数模块，以 ecloud 开头的函数提供：

• 无需对接，直接调用函数即可与云控进行交互；
• 获取云控的数据、上报日志、操作数据共享表与缓存；
• 典型使用：任务参数下发、账号数据共享、运行日志回传、状态上报。

二、完整实例：从取参数到操作数据

function main() {
    // 如果自动化服务正常
    if (!autoServiceStart(3)) {
        logd("自动化服务启动失败，无法执行脚本");
        exit();
        return;
    }
    logd("开始执行脚本...{} = {}", ecloud.getDeviceNo(), ecloud.getCloudUrl());

    // 获取当前任务信息
    let ts = ecloud.getTaskInfo();
    if (ts == null) {
        logd("没有任务信息");
        return;
    }
    logd("任务信息:" + JSON.stringify(ts));
    logd(ts["taskName"]);
    if (ts.valueJson) {
        // 获取任务-参数设定中 名称 = haoma 的值
        logd("valueJson " + ts.valueJson["haoma"]);
        // 获取任务-参数设定中 名称 = 账号 的值
        logd("valueJson " + ts.valueJson['账号']);
    }

    // 这里开始编写你要的业务逻辑
    clickSettingTask();
    sleep(3000)
    // 对数据进行增删改查、追加和移出一条的演示
    dataOptDemo()
}

三、基础操作函数

函数	作用
ecloud.log	发送日志到云控
ecloud.getDeviceNo()	获取机器编号
ecloud.getDeviceId()	获取设备 ID
ecloud.getCloudUrl()	获取云控的 URL 地址
ecloud.getTaskInfo()	获取当前任务信息（含任务名 taskName 与参数 valueJson）
ecloud.removeScriptFile()	清除脚本（一次性任务跑完自动清理）

四、数据共享表操作（设备间共享数据）

数据共享表按组名组织，适合设备间共享账号、关键词等业务数据：

function dataOptDemo() {
    // 按照组名获取数据
    let data = ecloud.getData({ "groupName": "账号组2" });
    if (data) {
        logd("账号组2数据: " + JSON.stringify(data));
    }

    // 组名 + 指定的数据名 获取数据
    data = ecloud.getData({ "groupName": "账号组2", "dataName": "001-1112" });

    // 新增数据
    let d = ecloud.addData({
        "groupName": "账号组2",
        "dataName": ecloud.getDeviceNo() + "-111",
        "content": "xxx" + new Date()
    });

    // 更新数据
    let update2 = ecloud.updateData({
        "groupName": "账号组2",
        "dataName": ecloud.getDeviceNo() + "-111",
        "content": "牛逼" + new Date()
    });

    // 按组 + 数据名删除数据
    // let remove2 = ecloud.removeData({ "groupName": "账号组2", "dataName": "..." });
    // 按组删除数据
    let remove3 = ecloud.removeData({ "groupName": "账号组2" });

    // 追加一行数据
    let append1 = ecloud.appendOneLineData({
        "groupName": "账号组2",
        "dataName": ecloud.getDeviceNo() + "-111",
        "content": "我是要增加的数据1"
    });

    // 删除一行数据
    let removeline1 = ecloud.removeOneLineData({
        "groupName": "账号组2",
        "dataName": ecloud.getDeviceNo() + "-111",
        "content": "我是要增加的数据1"
    });
}

函数速查：

函数	作用
getData	按组或组+数据名取得数据
getDataPop	取得并删除数据
addData	新增数据
updateData	修改数据
removeData	删除数据（按组或按组+数据名）
appendOneLineData	追加一条数据
removeOneLineData	删除一条数据

五、动态数据接口（动态建表）

适合表结构不固定的业务，动态创建和操作表：

函数	作用
dynamicCreateTable	动态创建更新表
dynamicQuery	动态查询表数据
dynamicAdd	动态增加表数据
dynamicUpdate	动态更新表数据
dynamicRemove	动态删除表数据

六、数据缓存接口（高频临时数据）

缓存适合高频读写、临时性强的数据，如运行状态、计数、临时标记：

函数	作用
addCache	新增缓存
getCache	获取缓存
updateCache	更新缓存
updateCacheExpire	更新过期时间
getCacheExpire	获取剩余过期时间
removeCache	删除缓存
appendOneLineCache	追加缓存
removeOneLineCache	删除一行缓存
incrementCache	自增缓存（计数器）
decrementCache	自减缓存
popPushCache	push 或 pop 命令（队列操作）

七、常见问题

云控脚本函数需要单独集成 SDK 吗？

不需要。这是官方开放的脚本函数模块，EC 脚本内直接调用 ecloud 开头的函数即可，与云控的连接由平台内置通道完成。

任务参数怎么传进脚本？

在云控建任务时配置「参数设定」，脚本里用 ecloud.getTaskInfo() 拿到 valueJson，按参数名取值（如 ts.valueJson["haoma"]）。

多台设备同时读写共享表会冲突吗？

共享表按组名 + 数据名组织，建议用 ecloud.getDeviceNo() 作为数据名的一部分做设备级隔离（如 设备编号-111），避免多设备写入互相覆盖。

八、总结

ecloud 脚本函数把云控的“云端能力”变成了脚本里的“内置函数”：

• 任务感知：getTaskInfo 拿到任务名与参数，一个任务多设备差异化执行；
• 数据共享：共享表按组存取，设备间账号/关键词互通；
• 动态建表：表结构不固定也能灵活存取；
• 缓存与计数：自增自减、队列操作，高频场景不愁；
• 日志回传：ecloud.log 把每台设备的运行情况汇总到云端。

云控脚本函数，是脚本从“单机自治”走向“云端协作”的那座桥。