DeviceFarmer/STF项目API使用指南：设备管理与远程调试-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00209/article/details/148552253

DeviceFarmer/STF项目API使用指南：设备管理与远程调试

stf 项目地址: https://gitcode.com/gh_mirrors/stf/stf

概述

DeviceFarmer/STF（Smartphone Test Farm）是一个强大的移动设备管理平台，它提供了一套完整的RESTful API接口，允许开发者通过编程方式管理测试设备。本文将详细介绍STF API的核心功能和使用方法，帮助开发者快速掌握设备管理、远程调试等关键操作。

API基础架构

STF API基于Swagger规范构建，这意味着：

接口定义清晰规范，符合RESTful设计原则
支持自动生成多种语言的客户端SDK
提供交互式API文档，便于开发者探索和测试接口

认证机制

STF采用OAuth 2.0认证机制，使用API前需要获取访问令牌：

登录STF Web界面
进入"设置"→"密钥"选项卡
生成新的访问令牌（注意：令牌仅显示一次，请妥善保存）

使用令牌时，需要在每个请求的Header中加入：

Authorization: Bearer YOUR-TOKEN-HERE

核心API功能详解

设备管理

获取设备列表

获取STF平台管理的所有设备信息（包括离线设备）：

GET /api/v1/devices

可选参数：

fields：指定返回字段，如serial,using,ready

获取特定设备详情

通过设备序列号查询特定设备状态：

GET /api/v1/devices/{serial}

用户设备操作

占用设备（相当于Web界面的"使用"按钮）：
```
POST /api/v1/user/devices
```
请求体需包含设备序列号：
```
{"serial":"设备序列号"}
```
释放设备（相当于"停止使用"）：
```
DELETE /api/v1/user/devices/{serial}
```
查询用户当前占用的设备：
```
GET /api/v1/user/devices
```

远程调试功能

STF API提供了强大的远程调试支持：

建立远程连接：

POST /api/v1/user/devices/{serial}/remoteConnect

返回示例：

{
  "success": true,
  "remoteConnectUrl": "IP地址:端口号"
}

获取URL后，可通过adb connect IP地址:端口号连接设备。

断开远程连接：

DELETE /api/v1/user/devices/{serial}/remoteConnect

重要提示：使用远程调试前，请确保已将ADB公钥添加到STF系统中，否则设备可能处于未授权状态。

实用示例

Shell脚本示例

#!/bin/bash

# 设备管理函数库
function add_device {
  # 占用设备实现
  response=$(curl -X POST -H "Content-Type: application/json" \
           -H "Authorization: Bearer $STF_TOKEN" \
           --data "{\"serial\": \"$DEVICE_SERIAL\"}" $STF_URL/api/v1/user/devices)
  # 处理响应...
}

function remote_connect {
  # 建立远程连接实现
  response=$(curl -X POST -H "Authorization: Bearer $STF_TOKEN" \
            $STF_URL/api/v1/user/devices/$DEVICE_SERIAL/remoteConnect)
  # 处理响应并连接ADB...
}

function remove_device {
  # 释放设备实现
  response=$(curl -X DELETE -H "Authorization: Bearer $STF_TOKEN" \
            $STF_URL/api/v1/user/devices/$DEVICE_SERIAL)
  # 处理响应...
}

Node.js示例

设备连接与远程调试

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

async function connectDevice(serial) {
  const client = await new Swagger({
    url: 'API地址',
    usePromise: true,
    authorizations: {
      accessTokenAuth: new Swagger.ApiKeyAuthorization('Authorization', 'Bearer 令牌', 'header')
    }
  });

  // 检查设备状态
  const deviceRes = await client.devices.getDeviceBySerial({
    serial: serial,
    fields: 'serial,present,ready,using,owner'
  });
  
  const device = deviceRes.obj.device;
  if (!device.present || !device.ready || device.using || device.owner) {
    throw new Error('设备不可用');
  }

  // 占用设备
  const addRes = await client.user.addUserDevice({
    device: { serial: device.serial, timeout: 900000 }
  });
  
  if (!addRes.obj.success) {
    throw new Error('占用设备失败');
  }

  // 获取远程连接URL
  const connectRes = await client.user.remoteConnectUserDeviceBySerial({
    serial: device.serial
  });
  
  return connectRes.obj.remoteConnectUrl;
}