深入解析DeviceHub项目中的STF API使用指南

项目背景与API概述

DeviceHub项目提供了一个基于RESTful架构的STF API，主要用于管理和控制测试设备资源。这套API基于Swagger规范实现，允许开发者通过编程方式完成设备的预约、释放等操作，为自动化测试和设备管理提供了极大便利。

核心功能模块

1. 认证机制

STF API采用OAuth 2.0认证协议，使用Bearer Token进行身份验证。获取访问令牌的步骤如下：

1. 登录STF Web界面
2. 进入"设置"选项卡
3. 在"密钥"部分生成新的访问令牌
4. 妥善保存生成的令牌（注意：令牌仅显示一次）

所有API请求都必须在Header中包含授权信息：

Authorization: Bearer YOUR-TOKEN-HERE

2. 设备管理功能

设备查询

• 获取所有设备列表：GET /api/v1/devices
• 获取特定设备详情：GET /api/v1/devices/{serial}

设备操作

• 更新设备信息：PUT /api/v1/devices/{serial}
• 添加设备到用户账户：POST /api/v1/user/devices
• 从用户账户移除设备：DELETE /api/v1/user/devices/{serial}

3. 远程连接功能

STF API提供了远程调试设备的接口：

• 建立远程连接：POST /api/v1/user/devices/{serial}/remoteConnect
• 断开远程连接：DELETE /api/v1/user/devices/{serial}/remoteConnect

实战应用示例

使用cURL操作设备

1. 查询所有设备：

curl -H "Authorization: Bearer YOUR-TOKEN" https://stf.example.org/api/v1/devices | jq .

2. 添加设备到用户账户：

curl -X POST -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR-TOKEN" \
     --data '{"serial":"DEVICE_SERIAL"}' \
     https://stf.example.org/api/v1/user/devices

使用Node.js开发自动化脚本

1. 设备连接脚本示例：

const Swagger = require('swagger-client');

const client = new Swagger({
  url: 'https://stf.example.org/api/v1/swagger.json',
  usePromise: true,
  authorizations: {
    accessTokenAuth: new Swagger.ApiKeyAuthorization(
      'Authorization', 
      'Bearer YOUR-TOKEN', 
      'header'
    )
  }
});

async function connectDevice(serial) {
  try {
    const api = await client;
    const deviceRes = await api.devices.getDeviceBySerial({serial});
    
    if (!deviceRes.obj.device.ready) {
      throw new Error('Device not available');
    }

    const addRes = await api.user.addUserDevice({
      device: {serial, timeout: 900000}
    });
    
    const connectRes = await api.user.remoteConnectUserDeviceBySerial({serial});
    console.log('Remote connect URL:', connectRes.obj.remoteConnectUrl);
    
    return connectRes.obj.remoteConnectUrl;
  } catch (error) {
    console.error('Operation failed:', error);
    throw error;
  }
}

2. 设备断开脚本示例：

async function disconnectDevice(serial) {
  try {
    const api = await client;
    const res = await api.user.deleteUserDeviceBySerial({serial});
    
    if (res.obj.success) {
      console.log('Device disconnected successfully');
      return true;
    }
    throw new Error('Disconnect operation failed');
  } catch (error) {
    console.error('Disconnect failed:', error);
    throw error;
  }
}

最佳实践建议

1. 错误处理：所有API调用都应该包含完善的错误处理逻辑，特别是网络请求和异步操作。

2. 资源释放：使用完设备后务必调用释放接口，避免设备被长时间占用。

3. 超时设置：添加设备时建议设置合理的超时时间，防止设备被无限期占用。

4. 响应格式化：使用jq工具可以方便地格式化和筛选API返回的JSON数据。

5. ADB密钥管理：使用远程连接功能前，确保已将ADB公钥添加到STF系统中。

常见问题解决方案

1. 设备不可用：检查设备状态是否ready且未被占用，确认设备物理连接正常。

2. 认证失败：确认访问令牌有效且未过期，检查请求头格式是否正确。

3. 远程连接问题：确认ADB密钥已正确配置，检查网络连接是否正常。

通过本文介绍的STF API使用方法，开发者可以轻松实现测试设备的自动化管理，大幅提升移动应用测试效率。无论是简单的设备查询还是复杂的自动化测试流程，这套API都能提供强大的支持。