在自动化脚本开发中，设备信息的获取与操控是构建稳定、智能脚本的基础，覆盖了从移动端脚本内实时获取设备信息，到服务端远程管理设备生命周期的全链路能力。本文将系统梳理设备相关 API 的分类、功能与典型用法。

一、设备操作 API 的整体架构

冰狐智能辅助的设备操作能力主要分布在三个层面：

1. 移动端脚本 API：在设备上运行的 JavaScript 脚本中直接调用，用于获取当前设备的硬件信息与系统状态。

2. OpenAPI（开放接口）：面向开发者的 HTTP API，用于在自己的后端服务中集成冰狐的设备管理能力。

3. 服务端 API（BaaS）：冰狐平台内置的后端接口，供平台内的微服务或管理端调用。

三者分工明确：移动端 API 解决“脚本知道自己在什么设备上运行”的问题，OpenAPI 和服务端 API 解决“远程如何管理和调度设备”的问题。

二、移动端脚本中的设备信息获取 API

在冰狐的移动端脚本中，可以直接调用一系列无参函数来获取当前设备的各类信息：

getDeviceName()——获取当前设备在冰狐智能辅助 App 中显示的名称，返回字符串类型。这是最常用的设备标识 API，可用于日志输出或条件判断。

var name = getDeviceName(); console.log('设备名:' + name);

getDeviceModel()——获取当前设备的型号，返回字符串。例如“Xiaomi MIX 4”或“Redmi K50”等。

var ret = getDeviceModel(); console.log('设备型号:' + ret);

getManufacturer()——获取设备制造商信息，返回字符串。

var ret = getManufacturer(); console.log('制造商:' + ret);

getSystemVersion()——获取当前设备的操作系统版本，返回字符串。

var ret = getSystemVersion(); console.log('操作系统版本:' + ret);

getDeviceDays()——获取当前设备的剩余可用天数，返回整数类型。该 API 常用于检测设备授权状态，当可用天数不足时可提前预警。

var ret = getDeviceDays(); console.log('设备可用天数:' + ret);

getVolume()/getMaxVolume()/setVolume()——音量相关的三个 API。getVolume()返回当前音量值（整数），getMaxVolume()返回设备支持的最大音量值，setVolume(value)用于设置音量。音量控制在某些需要调节系统音量的自动化场景中非常实用。

var current = getVolume(); var max = getMaxVolume(); console.log('当前音量:' + current + ', 最大音量:' + max); setVolume(10); // 将音量设置为10

这些 API 的共同特点是：除setVolume外均为无参调用，返回值类型明确（字符串或整数），可直接在脚本中赋值使用。它们为脚本提供了对运行环境的“自我认知”能力，是实现设备自适应逻辑的基础。

此外，getDeviceCustomData(key, defaultValue)函数可从网页端「移动端」/「设备管理」中预设的自定义数据中读取值。这为脚本提供了灵活的配置注入渠道——运维人员无需修改脚本代码，只需在管理后台调整自定义数据即可改变脚本行为。

三、OpenAPI：服务端远程设备管理

OpenAPI 面向需要在自有后端服务中集成冰狐设备管理能力的开发者，所有接口统一返回 JSON 数据格式。使用前需先通过clientKey和clientSecret获取accessToken。

获取设备列表（GET /api/device/list）——返回指定用户下的所有设备信息，支持分页。响应中的每个设备对象包含uuid、name、phoneNumber、extraData、enable（是否可用）、days（可用天数）、onlineState（在线状态）、workState（工作状态）等字段。

获取设备信息（GET /api/device/get_info）——根据设备uuid获取单个设备的详细信息。

获取设备状态（GET /api/device/state）——获取设备的在线状态和工作状态。onlineState为 0 表示离线，1 表示在线，2 表示在线但服务不可用；workState为 0 表示空闲，1 表示繁忙。

启动设备（GET /api/device/start）——启动指定设备并执行脚本。支持传入单个uuid或多个uuid组成的 JSON 数组，可实现批量启动。若scriptName不为空则执行指定脚本，否则依次查找设备默认脚本和用户默认脚本。

停止设备（GET /api/device/stop）——停止指定设备上正在运行的脚本。

设置设备自定义数据（GET /api/device/set_extra_data）——为设备写入自定义数据，供脚本端通过getDeviceCustomData读取。

OpenAPI 的价值在于将冰狐的设备管理能力嵌入到开发者自己的后台系统中，实现设备注册、状态监控、脚本调度等功能的自动化运维。

四、服务端 API（BaaS）：平台内的设备管理

服务端 API 主要用于冰狐平台内部的微服务或管理端调用，与 OpenAPI 在功能上有一定重叠，但调用方式和上下文不同。

deviceList(openId, startIndex, itemCount)——返回指定用户下的设备列表。每个设备对象包含uuid、name、phoneNumber、extraData、enable、days、onlineState、workState、devState（开发模式/发布模式）等字段。

getDeviceInfo(uuid)——获取单个设备的完整信息。

getDeviceState(uuid)——获取设备在线状态和工作状态。

deviceStart(uuid, scriptName)——启动设备并执行脚本。

deviceReset(uuid, refreshApp)——停止设备上正在运行的脚本。

setDeviceExtraData(uuid, data)——为设备设置自定义数据。

服务端 API 与 OpenAPI 的核心区别在于：服务端 API 运行在冰狐平台内部环境中，无需传递clientKey和accessToken，调用更简洁；而 OpenAPI 面向外部开发者，需要独立的鉴权机制。

五、典型应用场景与实践建议

综合以上 API，冰狐平台的设备操作能力可支撑以下典型场景：

场景一：设备自适应的脚本逻辑。在移动端脚本开头调用getDeviceModel()和getSystemVersion()，根据设备型号和系统版本调整 UI 控件的查找策略或点击坐标偏移量，提升脚本在不同设备上的兼容性。

场景二：设备健康度监控。通过 OpenAPI 或服务端 API 定期轮询设备列表，检查days（剩余天数）和onlineState（在线状态），当设备即将过期或离线时触发告警通知。

场景三：远程批量任务调度。使用 OpenAPI 的/api/device/start接口，传入多个设备uuid组成的数组，实现批量启动脚本执行任务。

场景四：动态配置注入。运维人员在网页端「设备管理」中修改设备的自定义数据，脚本端通过getDeviceCustomData()实时读取最新配置，无需重新发布脚本即可调整运行参数。

六、总结

冰狐智能辅助平台的设备操作 API 体系设计清晰、层次分明：

• 移动端脚本 API（getDeviceName、getDeviceModel、getManufacturer、getSystemVersion、getDeviceDays、音量相关函数等）为脚本提供了完备的设备信息感知能力，是编写健壮自动化脚本的基础工具。

• OpenAPI将设备管理能力对外开放，使开发者能够将冰狐的设备资源纳入自有后台管理体系。

• 服务端 API为平台内部的微服务和管理端提供了便捷的设备操作接口。

三者结合，构成了从“设备端感知”到“服务端管控”的完整闭环，为自动化脚本的开发、部署和运维提供了坚实的技术支撑。在实际开发中，建议根据具体场景选择合适的 API 层级，避免跨层调用带来的不必要的复杂度。