深入理解OpenSTF项目中的RESTful API接口-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00450/article/details/148391912

深入理解OpenSTF项目中的RESTful API接口

stf Control and manage Android devices from your browser. 项目地址: https://gitcode.com/gh_mirrors/st/stf

前言

OpenSTF是一个强大的移动设备管理平台，它提供了一套完整的RESTful API接口，允许开发者以编程方式管理设备。本文将全面解析STF API的设计理念、使用方法和实际应用场景，帮助开发者更好地利用这套接口进行自动化设备管理。

STF API概述

STF API采用RESTful架构风格设计，基于HTTP协议提供设备管理功能。这套API的核心价值在于：

提供标准化的设备管理接口
支持多种编程语言调用
实现自动化设备分配和释放
支持远程调试功能

API内部采用Swagger规范实现，这意味着开发者可以自动生成各种语言的客户端SDK，极大简化了集成工作。

认证机制

STF采用OAuth 2.0认证协议，使用Bearer Token进行身份验证。获取和使用Token的流程如下：

从STF Web界面的"设置"→"Keys"部分生成访问令牌
妥善保存生成的Token（界面只显示一次）
在每次API请求的Header中加入认证信息

认证Header格式示例：

Authorization: Bearer YOUR_TOKEN_HERE

核心API功能详解

1. 设备管理接口

获取设备列表

端点：GET /api/v1/devices
功能：获取STF平台管理的所有设备信息（包括离线设备）
可选参数：fields用于指定返回字段，如serial,using,ready

获取特定设备信息

端点：GET /api/v1/devices/{serial}
功能：查询指定序列号设备的详细信息
用途：检查设备状态、可用性等

2. 用户设备操作接口

添加设备到用户账户

端点：POST /api/v1/user/devices
请求体：{"serial":"设备序列号"}
功能：相当于Web界面中的"使用"按钮操作

从用户账户移除设备

端点：DELETE /api/v1/user/devices/{serial}
功能：释放设备，相当于Web界面中的"停止使用"操作

获取用户当前使用的设备

端点：GET /api/v1/user/devices
功能：列出当前用户占用的所有设备

3. 远程调试接口

建立远程连接

端点：POST /api/v1/user/devices/{serial}/remoteConnect
响应：返回可adb connect的远程地址
注意：需提前配置好ADB密钥

断开远程连接

端点：DELETE /api/v1/user/devices/{serial}/remoteConnect
功能：终止远程调试会话

实战示例

使用cURL操作设备

# 获取所有设备
curl -H "Authorization: Bearer YOUR_TOKEN" https://stf.example.org/api/v1/devices

# 添加设备到账户
curl -X POST -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     --data '{"serial":"EP7351U3WQ"}' \
     https://stf.example.org/api/v1/user/devices

Node.js客户端实现

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'
    )
  }
});

// 获取用户信息示例
client.then(api => {
  api.user.getUser()
    .then(res => console.log(res.obj.user.email))
    .catch(console.error);
});

完整的设备使用流程脚本

#!/bin/bash
# 设备使用全流程：添加→连接→使用→释放

# 1. 添加设备
curl -X POST -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     --data "{\"serial\":\"$SERIAL\"}" \
     $STF_URL/api/v1/user/devices

# 2. 建立远程连接
REMOTE_URL=$(curl -X POST -H "Authorization: Bearer $TOKEN" \
     $STF_URL/api/v1/user/devices/$SERIAL/remoteConnect | jq -r .remoteConnectUrl)

# 3. 连接ADB
adb connect $REMOTE_URL

# ...执行测试...

# 4. 释放设备
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
     $STF_URL/api/v1/user/devices/$SERIAL