Appium 协议端点全解析从会话管理到设备交互的官方 API 参考与实践【免费下载链接】appiumCross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol项目地址: https://gitcode.com/GitHub_Trending/ap/appium本指南以 Appium 官方文档《Appium Protocol》为骨架系统讲解 Appium 在 W3C WebDriver 协议之上扩展的全部专有 HTTP 端点覆盖会话发现、能力/设置/命令自省、上下文切换、事件日志、设备时间与 App 生命周期管理、键盘与文件操作、旋转与方向控制等主题。读完本文你将掌握每个端点的请求方法、路径、参数与响应结构并能结合仓库源码理解其在 AppiumDriver 与 BaseDriver 中的底层实现直接用于日常自动化脚本编写与排障。概览Appium 对 W3C WebDriver 协议的扩展Appium 构建在 W3C WebDriver 协议之上本仓库packages/appium包中实现的这些端点构成了 Appium 协议扩展Appium extension它们并未被 W3C 标准定义而是 Appium 为解决跨平台移动自动化需求补充的专有能力。在源码层面这些路由被集中声明在 路由定义文件会话/能力/设置/命令自省类与 设备交互路由文件App 生命周期、键盘、文件、时钟、旋转方向类中通过MethodMapDriver类型约束与payloadParams声明参数校验规则required/optional。也就是说每个端点的 HTTP 方法、路径与参数必填性都可以在这两份路由文件中得到第一手验证。从功能上这些端点可以划分为四大类| 类别 | 端点示例 | 说明 | |--|--|--| | 会话与自省 |/appium/sessions、/appium/capabilities、/appium/settings、/appium/commands、/appium/extensions| 服务端状态、会话能力、设置、支持的命令与扩展方法 | | 上下文与事件 |/appium/context、/appium/contexts、/appium/events、/appium/log_event| 原生/WebView 上下文切换、命令事件时间线记录 | | 设备与 App 管理 |/appium/device/activate_app、/appium/device/app_state、/appium/device/install_app等 | App 安装/卸载/启动/终止/状态查询 | | 设备交互 |/appium/device/hide_keyboard、/appium/device/push_file、/appium/device/rotation等 | 键盘、文件传输、旋转与方向 |会话发现与能力查询getAppiumSessions列出所有活跃会话GET /appium/sessions检索服务端所有活跃会话的信息。注意安全前置条件该端点依赖名为session_discovery的 insecure feature必须显式开启对应启动参数--allow-insecuresession_discovery或在配置中允许才可访问详见 安全指南 与 insecure 特性实现。源码中该端点由 getAppiumSessions 实现首先调用this.assertFeatureEnabled(SESSION_DISCOVERY_FEATURE)常量定义于 constants.ts未开启时直接抛错随后遍历内部this.sessions映射为每个会话组装出id、created会话创建时间戳与capabilities三项数据。响应TimestampedMultiSessionData[]数组中的每个会话对象包含| 名称 | 描述 | 类型 | |--|--|--| |capabilities| 会话能力 | object | |created| 会话创建时间Unix 毫秒时间戳 | number | |id| 会话 ID | string |用法提示该端点常用于调试与监控场景例如服务端在收到多个并发会话时快速盘点当前运行的自动化任务或用于 grid 场景下的健康检查。getAppiumSessionCapabilities读取当前会话能力GET /session/:sessionId/appium/capabilities检索当前会话的 会话能力。BaseDriver 中的实现非常简洁——直接返回{capabilities: this.caps}见 driver.ts。响应SessionCapabilities包含单一属性| 名称 | 描述 | 类型 | |--|--|--| |capabilities| 会话能力 | object |会话设置Settings的读取与更新Settings 是 Appium 提供的运行时可变配置机制与“创建会话时一次性传入的能力caps”不同Settings 可以在会话存活期间动态调整例如修改截图质量、元素定位等待策略等其完整清单可参考 设置指南。getSettings获取当前设置GET /session/:sessionId/appium/settings响应Settings——包含设置名称与对应值的对象。updateSettings更新指定设置POST /session/:sessionId/appium/settings更新指定的会话设置其余之前设置过的项保持不变即增量更新而非整体替换。参数| 名称 | 描述 | 类型 | |--|--|--| |settings| 要更新的设置名称与值组成的对象 | object |响应null源码实现位于 driver.tsupdateSettings委托给内部this.settings.update(newSettings)getSettings调用this.settings.getSettings()两者都会在this.settings不存在会话未正确初始化时抛出settings object not found错误。路由定义routes/appium.ts中payloadParams: {required: [settings]}表明settings是必填参数缺失时协议层会直接拒绝请求。命令与扩展自省listCommands 与 listExtensionslistCommands列出当前会话支持的全部命令GET /session/:sessionId/appium/commands检索当前会话支持的所有 URL 端点与 WebDriver BiDi 命令并按来源分组基础 Appium、driver 专属、plugin 专属。这在调试某个 driver 是否实现了某命令时非常有用。响应ListCommandsResponse——包含所有受支持端点与 BiDi 命令的对象按其来源基础 Appium / driver / plugin分组。结构细节可参考仓库中 types 包的命令类型定义。listExtensions列出当前会话支持的 execute 方法GET /session/:sessionId/appium/extensions检索当前会话支持的 execute 方法即通过driver.executeScript(mobile: xxx, args)调用的扩展能力。响应ListExtensionsResponse——包含所有受支持 execute 方法的对象按来源driver 专属 / plugin 专属分组。类型结构同样定义于 types 包命令类型。在协议层这两个命令分别对应常量LIST_DRIVER_COMMANDS_COMMAND与LIST_DRIVER_EXTENSIONS_COMMAND见 protocol.ts。结合 执行方法指南 可以理解execute 方法是 driver 或 plugin 在标准 HTTP 端点之外暴露自定义能力的主要通道而本端点正是对其进行动态枚举的自省入口。应用上下文Context管理Context 机制是 Appium 处理混合应用原生 WebView的核心概念。以下三个端点对应标准的 context 语义getCurrentAppiumContext获取当前上下文GET /session/:sessionId/appium/context响应string——当前激活上下文的名称如NATIVE_APP或WEBVIEW_1。setAppiumContext切换上下文POST /session/:sessionId/appium/context参数| 名称 | 描述 | 类型 | |--|--|--| |name| 要设置为激活状态的上下文名称 | string |响应nullgetAppiumContexts列出所有可用上下文GET /session/:sessionId/appium/contexts响应string[]——所有可用上下文的名称数组。路由映射routes/appium.ts中setContext声明了required: [name]。实现上这些方法由各 driver 自行实现仓库中的 fake-driver 上下文实现 提供了一个清晰的参考样例getContexts返回NATIVE_APP、PROXY以及应用模型中所有WEBVIEW_nsetContext在目标 context 存在时更新内部状态并联动 WebView 的激活/停用否则抛出NoSuchContextError。这说明上下文的具体语义与可用名称完全由 driver 决定Appium 协议层只负责转发与校验。事件时间线getLogEvents 与 logCustomEvent事件日志用于记录会话生命周期中的关键时间点常配合eventTimings能力eventTimings: true进行性能分析。getLogEvents获取事件历史POST /session/:sessionId/appium/events检索当前会话中已发生的事件。默认情况下日志中只记录 driver 命令的执行但 driver 或 plugin 可以定义额外的事件类型客户端也可以通过下述logCustomEvent端点主动记录自定义事件。参数| 名称 | 描述 | 类型 | |--|--|--| |type?| 用于过滤返回事件的一个或多个类型 | string 或 arraystring |响应EventHistory——一个对象其键对应已记录事件的类型。典型响应示例{ commands: [ { cmd: getStatus, startTime: 1756887645447, endTime: 1756887645454 } ], driverevent: [1756887645454], namespace:event: [1756887645454] }结构说明commands键始终存在其值为对象数组每个对象包含 3 个字段cmd所执行命令的名称startTime命令开始执行时间Unix 毫秒时间戳endTime命令结束执行时间Unix 毫秒时间戳其他非命名空间键由 driver/plugin 实现定义值为事件发生时间毫秒数组命名空间键如namespace:event可通过logCustomEvent写入也可由 driver/plugin 主动提供值同样为事件时间毫秒数组。源码实现事件命令实现当type参数为空时直接返回完整eventHistory否则将参数规范化为数组后仅返回命中所选事件类型的子集。logCustomEvent记录自定义事件POST /session/:sessionId/appium/log_event记录一个自定义事件之后可通过getLogEvents检索。参数| 名称 | 描述 | 类型 | |--|--|--| |vendor| 用于给事件加前缀的命名空间厂商名称 | string | |event| 事件名称 | string |响应null实现上event.ts将两个参数拼接为vendor:event形式写入内部事件历史——这正是响应中命名空间键的来源。协议层校验routes/appium.ts要求vendor与event均为必填。典型应用场景在测试脚本的关键业务节点埋点如登录开始购买完成随后结合命令执行时间绘制端到端性能瀑布图。设备时间与 App 生命周期管理getDeviceTime获取设备系统时间POST /session/:sessionId/appium/device/system_time参数| 名称 | 描述 | 类型 | 默认值 | |--|--|--|--| |format?| 返回时间戳使用的格式 | string |YYYY-MM-DDTHH:mm:ssZ|响应string——设备当前时间。该端点同时支持 GET 与 POST 两种方法见 appium-device.tsGET 不带参数、POST 可携带可选的format。activateApp激活 AppPOST /session/:sessionId/appium/device/activate_app在设备上激活前台运行一个 App。参数| 名称 | 描述 | 类型 | |--|--|--| |appId或bundleId| App 标识符如 Android 应用包名或 iOS bundle ID | string | |options?| driver 专属的启动选项 | unknown |响应voidterminateApp终止 AppPOST /session/:sessionId/appium/device/terminate_app终止设备上的一个 App。参数| 名称 | 描述 | 类型 | |--|--|--| |appId或bundleId| App 标识符 | string | |options?| driver 专属的终止选项 | unknown |响应voidqueryAppState查询 App 状态POST /session/:sessionId/appium/device/app_state参数| 名称 | 描述 | 类型 | |--|--|--| |appId或bundleId| App 标识符 | string |响应number——表示 App 状态的整数值| 数值 | App 状态 | |--|--| |0| 未安装 | |1| 未运行 | |2| 后台运行且已挂起 | |3| 后台运行 | |4| 前台运行 |installApp安装 AppPOST /session/:sessionId/appium/device/install_app参数| 名称 | 描述 | 类型 | |--|--|--| |appPath| App 文件的本地绝对路径或 URL | string | |options?| driver 专属的安装选项 | unknown |响应voidremoveApp卸载 AppPOST /session/:sessionId/appium/device/remove_app参数| 名称 | 描述 | 类型 | |--|--|--| |appId或bundleId| App 标识符 | string | |options?| driver 专属的卸载选项 | unknown |响应boolean——true表示卸载成功否则为false。isAppInstalled判断 App 是否已安装POST /session/:sessionId/appium/device/app_installed参数| 名称 | 描述 | 类型 | |--|--|--| |appId或bundleId| App 标识符 | string |响应boolean——true表示已安装否则为false。协议层校验要点路由文件appium-device.ts中activateApp、terminateApp、queryAppState、removeApp、isAppInstalled均使用required: [[appId], [bundleId]]这种**多选一**声明方式——即appId与bundleId至少提供其一即可installApp则要求appPath必填。这解释了文档中appId或bundleId的含义具体使用哪个键取决于目标平台Android 用包名、iOS 用 bundle ID请求中同时传两个也是允许的。键盘操作与文件传输hideKeyboard隐藏虚拟键盘POST /session/:sessionId/appium/device/hide_keyboard尝试隐藏设备上的虚拟键盘。参数全部可选appium-device.ts 将其声明为optional| 名称 | 描述 | 类型 | |--|--|--| |key?| 用于隐藏键盘的按键文本 | string | |keyCode?| 触发隐藏键盘的按键码 | string | |keyName?| 用于隐藏键盘的按键名称 | string | |strategy?| driver 专属的隐藏策略名称 | string |响应boolean——true表示操作成功否则为false。注意部分平台可能永远不会返回false例如某些 Android 实现直接执行隐藏动作而不检测结果。isKeyboardShown判断键盘是否显示GET /session/:sessionId/appium/device/is_keyboard_shown响应boolean——true表示键盘正在显示否则为false。pushFile向设备写入文件POST /session/:sessionId/appium/device/push_file参数| 名称 | 描述 | 类型 | |--|--|--| |data| 要写入文件的 Base64 编码数据 | string | |path| 设备上要创建文件的远程路径 | string |响应voidpullFile从设备读取文件POST /session/:sessionId/appium/device/pull_file参数| 名称 | 描述 | 类型 | |--|--|--| |path| 设备上文件的远程路径 | string |响应string——文件内容的 Base64 编码。pullFolder从设备读取目录POST /session/:sessionId/appium/device/pull_folder参数| 名称 | 描述 | 类型 | |--|--|--| |path| 设备上目录的远程路径 | string |响应string——目录内容打包成的 zip 文件的 Base64 编码。实用技巧pushFile/pullFile/pullFolder常用于自动化测试中的配置注入与日志/证据回收——例如把测试数据文件推入 App 沙盒或在用例结束后批量拉取崩溃日志与截图。Base64 编解码在主流语言客户端如 Java、Python、JS SDK中均有内置支持。设备旋转与方向控制getAppiumRotation获取空间旋转角度GET /session/:sessionId/appium/device/rotation响应Rotation——包含设备绕各轴旋转角度的对象| 名称 | 描述 | 类型 | |--|--|--| |x| 设备绕 X 轴旋转的度数 | number | |y| 设备绕 Y 轴旋转的度数 | number | |z| 设备绕 Z 轴旋转的度数 | number |setAppiumRotation设置空间旋转角度POST /session/:sessionId/appium/device/rotation参数| 名称 | 描述 | 类型 | |--|--|--| |x| 设备绕 X 轴旋转的度数 | number | |y| 设备绕 Y 轴旋转的度数 | number | |z| 设备绕 Z 轴旋转的度数 | number |响应null路由定义appium-device.ts明确x、y、z三项均为必填。getAppiumOrientation获取屏幕方向GET /session/:sessionId/appium/device/orientation响应string——PORTRAIT竖屏或LANDSCAPE横屏。setAppiumOrientation设置屏幕方向POST /session/:sessionId/appium/device/orientation参数| 名称 | 描述 | 类型 | |--|--|--| |orientation| 新的设备方向支持PORTRAIT或LANDSCAPE| string |响应null总结如何快速定位某个端点在阅读或调试 Appium 协议相关问题时建议遵循以下定位路径先查路由表协议路由 与 设备路由 定义了每个端点的 HTTP 方法与参数校验是最权威的接口契约再找实现getAppiumSessions等会话级方法在 AppiumDriver 中设置、能力、事件等通用方法在 BaseDriver 与 事件命令实现 中设备类方法由各 driver 实现参考 fake-driver 上下文实现 的写法对照类型定义types 包 中的MethodMap等类型定义给出了响应结构的完整形状。通过路由表 → 实现 → 类型三层对照任何端点的行为细节都可以在仓库内闭环验证无需依赖外部资料。【免费下载链接】appiumCross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol项目地址: https://gitcode.com/GitHub_Trending/ap/appium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Appium 协议端点全解析：从会话管理到设备交互的官方 API 参考与实践
Appium 协议端点全解析从会话管理到设备交互的官方 API 参考与实践【免费下载链接】appiumCross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol项目地址: https://gitcode.com/GitHub_Trending/ap/appium本指南以 Appium 官方文档《Appium Protocol》为骨架系统讲解 Appium 在 W3C WebDriver 协议之上扩展的全部专有 HTTP 端点覆盖会话发现、能力/设置/命令自省、上下文切换、事件日志、设备时间与 App 生命周期管理、键盘与文件操作、旋转与方向控制等主题。读完本文你将掌握每个端点的请求方法、路径、参数与响应结构并能结合仓库源码理解其在 AppiumDriver 与 BaseDriver 中的底层实现直接用于日常自动化脚本编写与排障。概览Appium 对 W3C WebDriver 协议的扩展Appium 构建在 W3C WebDriver 协议之上本仓库packages/appium包中实现的这些端点构成了 Appium 协议扩展Appium extension它们并未被 W3C 标准定义而是 Appium 为解决跨平台移动自动化需求补充的专有能力。在源码层面这些路由被集中声明在 路由定义文件会话/能力/设置/命令自省类与 设备交互路由文件App 生命周期、键盘、文件、时钟、旋转方向类中通过MethodMapDriver类型约束与payloadParams声明参数校验规则required/optional。也就是说每个端点的 HTTP 方法、路径与参数必填性都可以在这两份路由文件中得到第一手验证。从功能上这些端点可以划分为四大类| 类别 | 端点示例 | 说明 | |--|--|--| | 会话与自省 |/appium/sessions、/appium/capabilities、/appium/settings、/appium/commands、/appium/extensions| 服务端状态、会话能力、设置、支持的命令与扩展方法 | | 上下文与事件 |/appium/context、/appium/contexts、/appium/events、/appium/log_event| 原生/WebView 上下文切换、命令事件时间线记录 | | 设备与 App 管理 |/appium/device/activate_app、/appium/device/app_state、/appium/device/install_app等 | App 安装/卸载/启动/终止/状态查询 | | 设备交互 |/appium/device/hide_keyboard、/appium/device/push_file、/appium/device/rotation等 | 键盘、文件传输、旋转与方向 |会话发现与能力查询getAppiumSessions列出所有活跃会话GET /appium/sessions检索服务端所有活跃会话的信息。注意安全前置条件该端点依赖名为session_discovery的 insecure feature必须显式开启对应启动参数--allow-insecuresession_discovery或在配置中允许才可访问详见 安全指南 与 insecure 特性实现。源码中该端点由 getAppiumSessions 实现首先调用this.assertFeatureEnabled(SESSION_DISCOVERY_FEATURE)常量定义于 constants.ts未开启时直接抛错随后遍历内部this.sessions映射为每个会话组装出id、created会话创建时间戳与capabilities三项数据。响应TimestampedMultiSessionData[]数组中的每个会话对象包含| 名称 | 描述 | 类型 | |--|--|--| |capabilities| 会话能力 | object | |created| 会话创建时间Unix 毫秒时间戳 | number | |id| 会话 ID | string |用法提示该端点常用于调试与监控场景例如服务端在收到多个并发会话时快速盘点当前运行的自动化任务或用于 grid 场景下的健康检查。getAppiumSessionCapabilities读取当前会话能力GET /session/:sessionId/appium/capabilities检索当前会话的 会话能力。BaseDriver 中的实现非常简洁——直接返回{capabilities: this.caps}见 driver.ts。响应SessionCapabilities包含单一属性| 名称 | 描述 | 类型 | |--|--|--| |capabilities| 会话能力 | object |会话设置Settings的读取与更新Settings 是 Appium 提供的运行时可变配置机制与“创建会话时一次性传入的能力caps”不同Settings 可以在会话存活期间动态调整例如修改截图质量、元素定位等待策略等其完整清单可参考 设置指南。getSettings获取当前设置GET /session/:sessionId/appium/settings响应Settings——包含设置名称与对应值的对象。updateSettings更新指定设置POST /session/:sessionId/appium/settings更新指定的会话设置其余之前设置过的项保持不变即增量更新而非整体替换。参数| 名称 | 描述 | 类型 | |--|--|--| |settings| 要更新的设置名称与值组成的对象 | object |响应null源码实现位于 driver.tsupdateSettings委托给内部this.settings.update(newSettings)getSettings调用this.settings.getSettings()两者都会在this.settings不存在会话未正确初始化时抛出settings object not found错误。路由定义routes/appium.ts中payloadParams: {required: [settings]}表明settings是必填参数缺失时协议层会直接拒绝请求。命令与扩展自省listCommands 与 listExtensionslistCommands列出当前会话支持的全部命令GET /session/:sessionId/appium/commands检索当前会话支持的所有 URL 端点与 WebDriver BiDi 命令并按来源分组基础 Appium、driver 专属、plugin 专属。这在调试某个 driver 是否实现了某命令时非常有用。响应ListCommandsResponse——包含所有受支持端点与 BiDi 命令的对象按其来源基础 Appium / driver / plugin分组。结构细节可参考仓库中 types 包的命令类型定义。listExtensions列出当前会话支持的 execute 方法GET /session/:sessionId/appium/extensions检索当前会话支持的 execute 方法即通过driver.executeScript(mobile: xxx, args)调用的扩展能力。响应ListExtensionsResponse——包含所有受支持 execute 方法的对象按来源driver 专属 / plugin 专属分组。类型结构同样定义于 types 包命令类型。在协议层这两个命令分别对应常量LIST_DRIVER_COMMANDS_COMMAND与LIST_DRIVER_EXTENSIONS_COMMAND见 protocol.ts。结合 执行方法指南 可以理解execute 方法是 driver 或 plugin 在标准 HTTP 端点之外暴露自定义能力的主要通道而本端点正是对其进行动态枚举的自省入口。应用上下文Context管理Context 机制是 Appium 处理混合应用原生 WebView的核心概念。以下三个端点对应标准的 context 语义getCurrentAppiumContext获取当前上下文GET /session/:sessionId/appium/context响应string——当前激活上下文的名称如NATIVE_APP或WEBVIEW_1。setAppiumContext切换上下文POST /session/:sessionId/appium/context参数| 名称 | 描述 | 类型 | |--|--|--| |name| 要设置为激活状态的上下文名称 | string |响应nullgetAppiumContexts列出所有可用上下文GET /session/:sessionId/appium/contexts响应string[]——所有可用上下文的名称数组。路由映射routes/appium.ts中setContext声明了required: [name]。实现上这些方法由各 driver 自行实现仓库中的 fake-driver 上下文实现 提供了一个清晰的参考样例getContexts返回NATIVE_APP、PROXY以及应用模型中所有WEBVIEW_nsetContext在目标 context 存在时更新内部状态并联动 WebView 的激活/停用否则抛出NoSuchContextError。这说明上下文的具体语义与可用名称完全由 driver 决定Appium 协议层只负责转发与校验。事件时间线getLogEvents 与 logCustomEvent事件日志用于记录会话生命周期中的关键时间点常配合eventTimings能力eventTimings: true进行性能分析。getLogEvents获取事件历史POST /session/:sessionId/appium/events检索当前会话中已发生的事件。默认情况下日志中只记录 driver 命令的执行但 driver 或 plugin 可以定义额外的事件类型客户端也可以通过下述logCustomEvent端点主动记录自定义事件。参数| 名称 | 描述 | 类型 | |--|--|--| |type?| 用于过滤返回事件的一个或多个类型 | string 或 arraystring |响应EventHistory——一个对象其键对应已记录事件的类型。典型响应示例{ commands: [ { cmd: getStatus, startTime: 1756887645447, endTime: 1756887645454 } ], driverevent: [1756887645454], namespace:event: [1756887645454] }结构说明commands键始终存在其值为对象数组每个对象包含 3 个字段cmd所执行命令的名称startTime命令开始执行时间Unix 毫秒时间戳endTime命令结束执行时间Unix 毫秒时间戳其他非命名空间键由 driver/plugin 实现定义值为事件发生时间毫秒数组命名空间键如namespace:event可通过logCustomEvent写入也可由 driver/plugin 主动提供值同样为事件时间毫秒数组。源码实现事件命令实现当type参数为空时直接返回完整eventHistory否则将参数规范化为数组后仅返回命中所选事件类型的子集。logCustomEvent记录自定义事件POST /session/:sessionId/appium/log_event记录一个自定义事件之后可通过getLogEvents检索。参数| 名称 | 描述 | 类型 | |--|--|--| |vendor| 用于给事件加前缀的命名空间厂商名称 | string | |event| 事件名称 | string |响应null实现上event.ts将两个参数拼接为vendor:event形式写入内部事件历史——这正是响应中命名空间键的来源。协议层校验routes/appium.ts要求vendor与event均为必填。典型应用场景在测试脚本的关键业务节点埋点如登录开始购买完成随后结合命令执行时间绘制端到端性能瀑布图。设备时间与 App 生命周期管理getDeviceTime获取设备系统时间POST /session/:sessionId/appium/device/system_time参数| 名称 | 描述 | 类型 | 默认值 | |--|--|--|--| |format?| 返回时间戳使用的格式 | string |YYYY-MM-DDTHH:mm:ssZ|响应string——设备当前时间。该端点同时支持 GET 与 POST 两种方法见 appium-device.tsGET 不带参数、POST 可携带可选的format。activateApp激活 AppPOST /session/:sessionId/appium/device/activate_app在设备上激活前台运行一个 App。参数| 名称 | 描述 | 类型 | |--|--|--| |appId或bundleId| App 标识符如 Android 应用包名或 iOS bundle ID | string | |options?| driver 专属的启动选项 | unknown |响应voidterminateApp终止 AppPOST /session/:sessionId/appium/device/terminate_app终止设备上的一个 App。参数| 名称 | 描述 | 类型 | |--|--|--| |appId或bundleId| App 标识符 | string | |options?| driver 专属的终止选项 | unknown |响应voidqueryAppState查询 App 状态POST /session/:sessionId/appium/device/app_state参数| 名称 | 描述 | 类型 | |--|--|--| |appId或bundleId| App 标识符 | string |响应number——表示 App 状态的整数值| 数值 | App 状态 | |--|--| |0| 未安装 | |1| 未运行 | |2| 后台运行且已挂起 | |3| 后台运行 | |4| 前台运行 |installApp安装 AppPOST /session/:sessionId/appium/device/install_app参数| 名称 | 描述 | 类型 | |--|--|--| |appPath| App 文件的本地绝对路径或 URL | string | |options?| driver 专属的安装选项 | unknown |响应voidremoveApp卸载 AppPOST /session/:sessionId/appium/device/remove_app参数| 名称 | 描述 | 类型 | |--|--|--| |appId或bundleId| App 标识符 | string | |options?| driver 专属的卸载选项 | unknown |响应boolean——true表示卸载成功否则为false。isAppInstalled判断 App 是否已安装POST /session/:sessionId/appium/device/app_installed参数| 名称 | 描述 | 类型 | |--|--|--| |appId或bundleId| App 标识符 | string |响应boolean——true表示已安装否则为false。协议层校验要点路由文件appium-device.ts中activateApp、terminateApp、queryAppState、removeApp、isAppInstalled均使用required: [[appId], [bundleId]]这种**多选一**声明方式——即appId与bundleId至少提供其一即可installApp则要求appPath必填。这解释了文档中appId或bundleId的含义具体使用哪个键取决于目标平台Android 用包名、iOS 用 bundle ID请求中同时传两个也是允许的。键盘操作与文件传输hideKeyboard隐藏虚拟键盘POST /session/:sessionId/appium/device/hide_keyboard尝试隐藏设备上的虚拟键盘。参数全部可选appium-device.ts 将其声明为optional| 名称 | 描述 | 类型 | |--|--|--| |key?| 用于隐藏键盘的按键文本 | string | |keyCode?| 触发隐藏键盘的按键码 | string | |keyName?| 用于隐藏键盘的按键名称 | string | |strategy?| driver 专属的隐藏策略名称 | string |响应boolean——true表示操作成功否则为false。注意部分平台可能永远不会返回false例如某些 Android 实现直接执行隐藏动作而不检测结果。isKeyboardShown判断键盘是否显示GET /session/:sessionId/appium/device/is_keyboard_shown响应boolean——true表示键盘正在显示否则为false。pushFile向设备写入文件POST /session/:sessionId/appium/device/push_file参数| 名称 | 描述 | 类型 | |--|--|--| |data| 要写入文件的 Base64 编码数据 | string | |path| 设备上要创建文件的远程路径 | string |响应voidpullFile从设备读取文件POST /session/:sessionId/appium/device/pull_file参数| 名称 | 描述 | 类型 | |--|--|--| |path| 设备上文件的远程路径 | string |响应string——文件内容的 Base64 编码。pullFolder从设备读取目录POST /session/:sessionId/appium/device/pull_folder参数| 名称 | 描述 | 类型 | |--|--|--| |path| 设备上目录的远程路径 | string |响应string——目录内容打包成的 zip 文件的 Base64 编码。实用技巧pushFile/pullFile/pullFolder常用于自动化测试中的配置注入与日志/证据回收——例如把测试数据文件推入 App 沙盒或在用例结束后批量拉取崩溃日志与截图。Base64 编解码在主流语言客户端如 Java、Python、JS SDK中均有内置支持。设备旋转与方向控制getAppiumRotation获取空间旋转角度GET /session/:sessionId/appium/device/rotation响应Rotation——包含设备绕各轴旋转角度的对象| 名称 | 描述 | 类型 | |--|--|--| |x| 设备绕 X 轴旋转的度数 | number | |y| 设备绕 Y 轴旋转的度数 | number | |z| 设备绕 Z 轴旋转的度数 | number |setAppiumRotation设置空间旋转角度POST /session/:sessionId/appium/device/rotation参数| 名称 | 描述 | 类型 | |--|--|--| |x| 设备绕 X 轴旋转的度数 | number | |y| 设备绕 Y 轴旋转的度数 | number | |z| 设备绕 Z 轴旋转的度数 | number |响应null路由定义appium-device.ts明确x、y、z三项均为必填。getAppiumOrientation获取屏幕方向GET /session/:sessionId/appium/device/orientation响应string——PORTRAIT竖屏或LANDSCAPE横屏。setAppiumOrientation设置屏幕方向POST /session/:sessionId/appium/device/orientation参数| 名称 | 描述 | 类型 | |--|--|--| |orientation| 新的设备方向支持PORTRAIT或LANDSCAPE| string |响应null总结如何快速定位某个端点在阅读或调试 Appium 协议相关问题时建议遵循以下定位路径先查路由表协议路由 与 设备路由 定义了每个端点的 HTTP 方法与参数校验是最权威的接口契约再找实现getAppiumSessions等会话级方法在 AppiumDriver 中设置、能力、事件等通用方法在 BaseDriver 与 事件命令实现 中设备类方法由各 driver 实现参考 fake-driver 上下文实现 的写法对照类型定义types 包 中的MethodMap等类型定义给出了响应结构的完整形状。通过路由表 → 实现 → 类型三层对照任何端点的行为细节都可以在仓库内闭环验证无需依赖外部资料。【免费下载链接】appiumCross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol项目地址: https://gitcode.com/GitHub_Trending/ap/appium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考