# 云手机 API 能力目录 通过 API 将 Android 云手机的创建、日常操作、应用分发、文件传输和备份接入自己的业务系统。 ## 能力概览 | 模块 | 可以做什么 | | --------------------- | ---------------------------------------------------------------- | | [云机管理](#云机管理) | 管理云手机从创建、日常运行到回收的全过程，并调整设备与网络配置。 | | [镜像管理](#镜像管理) | 查看当前可用的系统镜像与机型，并用于创建云手机。 | | [任务管理](#任务管理) | 跟踪云手机操作的执行过程，查看每台设备的结果并处理异常反馈。 | | [应用管理](#应用管理) | 查询应用、分发安装包，并管理云手机上的应用运行和无障碍服务。 | | [文件管理](#文件管理) | 管理当前云卡的云端文件，并将文件或素材传送到云手机。 | | [备份管理](#备份管理) | 将云手机导出为备份，管理备份文件，并使用已有备份创建新云手机。 | ## 目录 - [云机管理](#云机管理) - [镜像管理](#镜像管理) - [任务管理](#任务管理) - [应用管理](#应用管理) - [文件管理](#文件管理) - [备份管理](#备份管理) - [配套能力](#配套能力) - [怎样接入](#怎样接入) - [技术人员参考](#技术人员参考) 具体可用操作受设备与交付环境影响；设备操作提交后需查询任务及每台设备的结果，受理成功不代表设备已执行完成。 ## 云机管理 管理云手机从创建、日常运行到回收的全过程，并调整设备与网络配置。 | 功能名称 | 功能说明 | | ------------ | --------------------------------------------------------------------------------------------------------------------- | | 查询云机列表 | 按名称、分组或状态等条件查找云手机，支持分页查看。 | | 查看云机详情 | 查看单台云手机的基础信息、所属资源和最近同步的状态。 | | 查看云机统计 | 汇总云手机数量、开关机状态及运行可用数量。 运行可用需要同时满足开机和网络可用；最近同步状态不保证此刻可连接或可投屏。 | | 创建云机 | 在选定云卡上按已有镜像和机型创建一台或多台云手机。 | | 开机 | 启动选定的云手机，支持对多台设备发起操作。 | | 关机 | 关闭选定的云手机，支持对多台设备发起操作。 | | 重启 | 重新启动选定的云手机。 | | 修改云机名称 | 为云手机设置便于业务识别的名称。 | | 管理云机分组 | 查看已有分组，并调整云手机的分组归属。 | | 回收云机 | 将暂不使用的云手机移入回收站。 | | 恢复回收云机 | 将回收站中的云手机恢复使用。 此功能恢复回收站中的原云机；从备份创建新云机请查看备份管理。 | | 永久删除云机 | 永久移除不再需要的云手机。 | | 修复云机 | 对异常云手机发起修复操作。 修复不会自动开关机或恢复出厂；操作后仍需确认设备是否恢复正常。 | | 恢复出厂 | 清除云手机中的应用和数据，保留基础硬件标识。 | | 一键新机 | 清除应用和数据，并重新生成基础配置及硬件标识。 | | 查询可用操作 | 查看某台云手机支持哪些操作，以及当前是否具备执行条件。 | | 查看内网地址 | 查看云手机最近读取到的内网地址，辅助连接和网络排查。 | | 查看当前配置 | 查看云手机最近读取到的分辨率、代理和域名解析设置。 | | 设置分辨率 | 调整云手机画面尺寸，或恢复设备默认分辨率。 | | 设置屏幕方向 | 将云手机设置为横屏、竖屏或反向显示。 | | 查看设备档案 | 查看可调整的设备档案字段与经过脱敏的现有值。 | | 修改设备档案 | 按指定内容或随机方式调整支持的设备标识档案。 | | 管理保存配置 | 查看或修改云手机保存的系统、网络、位置及设备标识等配置。 保存配置不会自动重启云手机，也不表示运行中的设备已采用新值。 | | 设置网络代理 | 为云手机保存网络代理设置，或改为直连。 | | 检测代理出口 | 检测机房通过指定代理或直连方式访问外网的出口。 检测结果反映机房出口，不证明云手机已经采用该代理设置。 | | 设置域名解析 | 为云手机保存域名解析服务器设置。 | | 模拟接收短信 | 向云手机注入指定发送方和内容的模拟短信。 这是模拟接收能力，不提供真实手机号、短信收发服务或验证码通道。 | ## 镜像管理 查看当前可用的系统镜像与机型，并用于创建云手机。 当前提供已有镜像的查询和选择，不包含镜像上传、制作、版本发布或分发管理。 镜像与机型列表来自最近同步的候选信息，创建时会再次核对实际条件。 | 功能名称 | 功能说明 | | ---------------- | ------------------------------------------------ | | 查询可用镜像 | 查看指定云卡当前提供的系统镜像候选。 | | 查看兼容机型 | 查看可选设备型号及其允许使用的镜像范围。 | | 使用镜像创建云机 | 从已有镜像和兼容机型中选择组合，创建新的云手机。 | ## 任务管理 跟踪云手机操作的执行过程，查看每台设备的结果并处理异常反馈。 任务管理跟踪已提交的设备操作，不提供定时调度或多步骤自动化工作流。 | 功能名称 | 功能说明 | | ------------------ | ------------------------------------------------------------------------------------------------------- | | 检查操作条件 | 在提交前检查选定设备的权限和当前执行条件。 | | 提交单台或批量操作 | 将选定设备的操作提交为可持续查询的任务。 | | 查看进度与结果 | 查询任务进度，并分别查看每台设备的成功、失败或待确认结果。 | | 查询任务历史 | 分页查看过去提交的操作及其目标和结果。 | | 请求取消任务 | 取消尚未发出的操作，并对已发出的操作记录取消请求。 已发出的设备操作不保证停止，仍需查询原任务确认结果。 | | 找回原提交结果 | 提交后未收到明确答复时，按原请求标识查找已受理的任务。 | | 核实结果不明的操作 | 查询原操作的处理情况或已生成文件，补全任务结果。 此功能查询原操作，不会再次执行同一设备操作。 | ## 应用管理 查询应用、分发安装包，并管理云手机上的应用运行和无障碍服务。 | 功能名称 | 功能说明 | | ------------------ | ------------------------------------------------------------------------------------------------- | | 查询已安装应用 | 查看云手机中已经安装的应用。 | | 浏览可安装应用 | 浏览交付环境提供的可安装应用目录。 应用目录由交付方配置；未配置目录时，仍可使用安装包或链接安装。 | | 安装已上传应用 | 将云端文件库中已上传完成的安装包安装到选定云手机。 | | 通过链接安装应用 | 从下载链接获取安装包并安装到选定云手机。 | | 启动应用 | 启动云手机上指定的已安装应用。 | | 停止应用 | 停止云手机上指定应用的运行。 | | 重启应用 | 重新启动云手机上的指定应用。 | | 卸载应用 | 从选定云手机中移除指定应用。 | | 查询应用无障碍服务 | 查看应用提供的无障碍服务及其状态。 | | 设置应用无障碍服务 | 启用或关闭指定的应用无障碍服务。 | | 打开应用无障碍入口 | 为指定应用打开其无障碍入口。 | | 隐藏应用无障碍入口 | 隐藏指定应用的无障碍入口。 隐藏无障碍入口不等于隐藏应用。 | ## 文件管理 管理当前云卡的云端文件，并将文件或素材传送到云手机。 上传完成只表示文件已保存到云端；安装应用或下发到手机需要另行发起操作。 云端文件库按当前云卡管理，不是跨云卡公共文件库；当前接口不提供手机内部文件的完整浏览、拉取或移动管理。 | 功能名称 | 功能说明 | | ---------------- | -------------------------------------------------------------------------------- | | 上传文件 | 将安装包、图片、视频等文件上传到当前云卡的云端文件库，支持分片传输和完整性校验。 | | 查询云端文件 | 分页查看当前云卡文件库中的文件，并按名称或类型筛选。 | | 查看文件状态 | 查看单个云端文件的信息，确认是否已完成上传并可使用。 | | 下载云端文件 | 下载已经就绪的云端文件，或生成有时效的下载链接。 | | 删除云端文件 | 删除当前文件库中不再需要的文件。 | | 下发已上传文件 | 将云端文件库中的文件发送到云手机的下载、图片、视频等指定类别目录。 | | 通过链接下发文件 | 从下载链接获取文件并发送到云手机的指定类别目录。 | | 获取云机截图 | 截取云手机画面，并通过云端文件获取图片。 | ## 备份管理 将云手机导出为备份，管理备份文件，并使用已有备份创建新云手机。 当前提供按需备份与恢复，不包含自动备份策略或定时保留管理；备份内容范围与恢复兼容性在交付时确认。 | 功能名称 | 功能说明 | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | 查询备份可用性 | 确认指定云手机当前是否支持备份及相关执行条件。 | | 创建备份 | 对选定云手机发起备份导出，并将生成文件交付到云端。 | | 查看备份历史 | 分页查看已经生成并交付完成的备份。 尚未完成的备份导出进度请查看原任务。 | | 下载备份 | 为已就绪的备份获取有时效的下载地址。 | | 删除备份 | 删除不再需要的备份文件。 | | 从备份创建云机 | 将已有且可使用的备份导入指定云卡，创建新的云手机。 恢复会创建新云机，保留原云机；需有权使用备份和目标云卡，跨机房兼容性须在交付时确认。 | ## 配套能力 ### 投屏与预览 为业务页面提供云手机画面查看、交互操作及相机素材设置。 | 功能名称 | 功能说明 | | -------------- | ------------------------------------------------------------------------------------------------------- | | 投屏并操作云机 | 获取云手机投屏连接，让获授权的用户查看画面并操作设备。 当前投屏连接包含设备控制能力，需要相应操作授权。 | | 查看只读预览 | 为多台云手机获取短时只读画面预览。 预览不提供设备控制；离线或关机时不保证能取得画面。 | | 设置相机图片 | 使用上传文件或图片链接为云手机设置相机底图。 | | 设置相机素材 | 用支持的图片或视频素材替换指定摄像头的画面来源。 设置后需在云手机上确认实际相机画面。 | ### 云卡与机房资源 查看承载云手机的云卡资源及所属机房，辅助安排创建和运维。 | 功能名称 | 功能说明 | | ------------ | ---------------------------------------- | | 查询云卡列表 | 查看当前可访问的云卡资源，并按条件筛选。 | | 查看云卡详情 | 查看单张云卡的信息与资源归属。 | | 查看云卡统计 | 汇总当前范围内云卡的数量与状态。 | | 查看所属机房 | 查看可见机房的名称和在线状态。 | ### 使用授权 将指定设备范围、操作权限和使用期限接入自己的业务登录体系。 撤销 API 使用授权不保证立即切断已建立的投屏连接，既有投屏票据按期限失效。 | 功能名称 | 功能说明 | | ---------------- | ---------------------------------------------------------- | | 开通受限使用授权 | 为业务用户发放限定设备范围、操作权限和有效期限的访问授权。 | | 调整使用授权 | 更新既有用户授权的设备范围、权限或有效期限。 | | 查询业务登录授权 | 根据自己的业务登录记录查找对应的使用授权。 | | 撤销指定授权 | 撤销某次使用授权，阻止其继续发起新的 API 访问。 | | 撤销业务登录授权 | 按业务登录记录撤销对应授权，用于业务退出或停用。 | ## 怎样接入 可由自己的业务系统接入 Core API，也可使用 Web Base 标准工作台管理云手机。 1. 先按本目录的功能模块确认业务需要，重点核对镜像、文件和备份的适用范围。 2. 确定合作后，由技术人员对接服务地址、访问授权、目标设备范围和异步任务结果。 3. 使用自己的业务页面或标准工作台完成联调，再按实际设备与交付环境验收。 ## 技术人员参考 合作对接时，技术人员可继续查看 [完整接口说明](openapi.md) 和 [OpenAPI 合同](openapi.json)，了解调用方法、参数与返回结果。