自动化脚本中如何操作自定义数据？

在自动化脚本开发中，数据的动态配置与灵活读取往往是决定脚本通用性和可维护性的关键。尤其是在多设备、多账号批量运行的场景下，将运行参数、账号信息、业务配置等数据从脚本代码中剥离出来，通过平台侧进行集中管理，可以极大降低脚本的维护成本。自动化脚本平台提供了完整的自定义数据管理体系，涵盖设备级 、用户级 、全局级 三个维度，并提供了smartGetCustomData等便捷函数来简化数据读取逻辑。本文将从实际开发角度出发，详细介绍如何在自动化脚本中操作自定义数据。

一、自定义数据的三种层级

冰狐的自定义数据分为三个层级，分别对应不同的管理粒度：

设备自定义数据：在网页端「移动端」→「设备管理」中选择具体设备，点击"自定义数据"按钮进行设置。该数据与特定设备绑定，适合存放设备独有的配置，如设备型号对应的不同参数、该设备专属的账号信息等。
用户自定义数据：在「管理中心」→「账户信息」的"自定义数据"中设置，每个子账户可以单独设置，子账户之间相互独立。适合存放不同账号的个性化配置，如不同账号的运营策略参数。
全局自定义数据：在「管理中心」→「自定义数据」中创建的全局数据项，在所有子账户中共享使用。适合存放所有设备、所有账号通用的配置，如统一的接口地址、通用的业务规则等。

二、核心API详解

1. getDeviceCustomData ------ 获取设备自定义数据

这是最常用的数据获取函数，用于读取当前设备绑定的自定义数据。

函数签名：

复制代码

getDeviceCustomData(key, defaultValue, useCache, type)

参数说明：

参数	类型	必填	说明
key	string	选填	要获取的数据键名，默认空表示返回所有数据
defaultValue	任意类型	选填	获取失败时的默认返回值
useCache	boolean	选填	是否优先从缓存获取，默认 true
type	string	选填	key的匹配类型：* 表示包含，^ 表示以key开始，$ 表示以key结束，默认精确匹配

使用示例：

复制代码

// 获取名为"name"的设备自定义数据
var ret = getDeviceCustomData('name');
console.log('设备自定义数据:' + ret);

// 获取所有数据（返回JSON数组字符串）
var allData = getDeviceCustomData();
console.log('所有自定义数据:' + allData);

// 带默认值，防止获取失败
var config = getDeviceCustomData('config', '{}');

2. getUserCustomData ------ 获取用户自定义数据

与设备级数据对应，该函数用于读取当前登录用户（子账户）的自定义数据。

使用示例：

复制代码

// 获取用户自定义数据，带默认值123
var data = getUserCustomData('key', 123);
console.log('用户数据:' + data);

3. getCustomData ------ 获取全局自定义数据

读取在管理中心创建的全局共享数据项。

使用示例：

复制代码

// 获取全局数据
var globalConfig = getCustomData('api_endpoint', 'https://default.api.com');
console.log('全局配置:' + globalConfig);

4. smartGetCustomData ------ 智能获取自定义数据

这是最实用的便捷函数，它会按照设备 → 用户 → 全局的优先级依次查找，返回第一个有效的数据。

使用示例：

复制代码

// 智能获取，优先设备级，其次用户级，最后全局级
var data = smartGetCustomData('key', 123);
console.log('获取到的数据:' + data);

5. setCustomData ------ 设置全局自定义数据

在移动端设置全局自定义数据项的值。需要注意的是，该API不会自动创建不存在的自定义数据项，需要先在管理中心创建好数据项才能设置。

使用示例：

复制代码

// 设置全局数据项的值
var success = setCustomData('config_key', 'new_value');
console.log('设置结果:' + success); // true/false

三、实际应用场景与脚本示例

场景一：多设备差异化配置

假设有10台设备运行同一个脚本，但每台设备需要执行不同的任务参数（如不同的商品ID、不同的关键词等）。传统做法是为每台设备单独维护一份脚本副本，维护成本极高。使用设备自定义数据可以完美解决：

步骤1：在网页端为每台设备设置自定义数据：

复制代码

设备A: {"task":"keyword_search","keyword":"手机","pages":5}
设备B: {"task":"keyword_search","keyword":"电脑","pages":3}
设备C: {"task":"detail_view","product_id":"10086"}

步骤2：脚本中统一读取：

复制代码

function main() {
    // 获取设备自定义数据
    var configStr = getDeviceCustomData();
    if (!configStr) {
        console.log('未配置设备数据，使用默认配置');
        configStr = '{"task":"default","keyword":"默认关键词"}';
    }
    
    var config = JSON.parse(configStr);
    var taskType = config.task || 'default';
    
    switch(taskType) {
        case 'keyword_search':
            searchKeyword(config.keyword, config.pages || 3);
            break;
        case 'detail_view':
            viewProductDetail(config.product_id);
            break;
        default:
            console.log('未知任务类型:' + taskType);
    }
}

场景二：账号与设备解耦

在批量运营场景中，经常需要将账号信息与设备解耦------同一台设备在不同时间段可能登录不同的账号。通过设备自定义数据存储当前绑定的账号信息，配合用户自定义数据存储账号的详细配置，可以实现灵活的账号切换：

复制代码

function main() {
    // 从设备自定义数据获取当前绑定的账号ID
    var accountId = getDeviceCustomData('account_id');
    if (!accountId) {
        console.log('设备未绑定账号');
        return;
    }
    
    // 从用户自定义数据获取该账号的详细配置（假设每个子账户对应一个账号）
    var accountConfig = getUserCustomData(accountId);
    if (!accountConfig) {
        console.log('未找到账号配置:' + accountId);
        return;
    }
    
    var config = JSON.parse(accountConfig);
    console.log('当前账号:' + config.username);
    // 执行登录及后续操作...
}

场景三：使用smartGetCustomData简化配置读取

在实际开发中，我们往往希望配置有"继承"或"覆盖"的层级关系------设备级配置覆盖用户级，用户级覆盖全局级。smartGetCustomData正好满足这一需求：

复制代码

function main() {
    // 智能获取"timeout"配置：优先设备级→用户级→全局级
    var timeout = smartGetCustomData('timeout', 30);
    
    // 智能获取"retry_count"配置
    var retryCount = smartGetCustomData('retry_count', 3);
    
    console.log('超时时间:' + timeout + '秒, 重试次数:' + retryCount);
    
    // 执行带配置的业务逻辑
    doTask(timeout, retryCount);
}

场景四：脚本运行结果回写

除了读取配置，脚本还可以将运行结果写回全局自定义数据，实现跨脚本、跨设备的数据共享：

复制代码

function main() {
    // 执行任务...
    var result = doSomeTask();
    
    // 将结果写入全局自定义数据（需先在管理中心创建数据项）
    var success = setCustomData('last_task_result', JSON.stringify(result));
    if (success) {
        console.log('结果已回写');
    } else {
        console.log('回写失败，请检查数据项是否已创建');
    }
}

四、最佳实践建议

1. 合理规划数据层级

设备级数据适合存放与硬件或具体设备实例强相关的配置；用户级数据适合存放账号维度的配置；全局级数据适合存放所有设备通用的配置。合理规划可以避免数据冗余，也便于批量管理。

2. 善用默认值

所有自定义数据获取函数都支持defaultValue参数。建议始终为关键配置提供合理的默认值，这样即使云端未配置，脚本也能正常运行，增强了脚本的健壮性。

3. JSON格式存储复杂数据

当需要存储结构化数据时，建议使用JSON格式。获取后通过JSON.parse()解析，设置前通过JSON.stringify()序列化。冰狐API返回的是字符串类型，多个值会返回JSON数组字符串。

4. 注意缓存策略

getDeviceCustomData的useCache参数默认为true，即优先从缓存读取。如果数据在脚本运行过程中可能被外部修改，且需要实时获取最新值，可以将useCache设为false。

5. 结合callScript实现模块化

冰狐的callScript函数可以同步调用其他脚本并获取返回值。可以将自定义数据的读取逻辑封装成独立的脚本模块，供多个主脚本复用，进一步提高代码的可维护性。

五、总结

冰狐自动化平台的自定义数据体系为脚本开发提供了灵活、高效的配置管理方案。通过getDeviceCustomData、getUserCustomData、getCustomData三个层级的精准读取，以及smartGetCustomData的智能优先级查找，开发者可以轻松实现脚本配置的集中化管理和动态化调整。配合setCustomData的回写能力，还可以实现脚本间数据的共享与流转。合理运用这些API，能够显著提升自动化脚本的通用性、可维护性和运行稳定性，是每一位冰狐自动化开发者都应该熟练掌握的核心技能。