STF API完全使用手册：从认证到设备管理的RESTful接口详解

【免费下载链接】stf 项目地址: https://gitcode.com/gh_mirrors/stf/stf

STF（Smartphone Test Farm）是一个开源的移动设备管理平台，提供强大的RESTful API接口，支持设备远程控制、自动化测试和批量管理。通过STF API，开发者可以轻松实现设备预约、远程调试、应用安装等操作，极大提升移动应用测试效率。🎯

STF API基于Swagger规范构建，支持自动生成API文档和多种编程语言的客户端SDK，让您能够以最便捷的方式集成设备管理功能到自己的测试流程中。

STF API架构概述

STF采用分布式架构设计，其核心组件通过消息队列进行通信。整个系统由多个模块组成，包括设备提供层（Provider）、处理层（Processor）、控制层（Control）和WebSocket连接层等。

STF API架构的核心特点：

• RESTful设计：遵循标准的HTTP协议和REST架构原则
• Swagger规范：支持自动生成API文档和客户端代码
• 分布式部署：支持多节点扩展，提高系统可用性
• 实时通信：通过WebSocket实现设备状态的实时更新

API认证与授权机制

STF使用OAuth 2.0认证机制，所有API请求都需要携带访问令牌（Access Token）。

获取访问令牌

在STF Web界面中，进入Settings → Keys，点击"Generate New Token"即可生成新的访问令牌。请务必妥善保存该令牌，因为系统不会再次显示。

认证头格式

在API请求中，必须在HTTP头中包含Authorization字段：

Authorization: Bearer YOUR-ACCESS-TOKEN

核心API接口详解

设备管理接口

获取设备列表

端点： GET /api/v1/devices

此接口返回所有STF设备信息，包括离线或不可访问的设备。

请求示例：

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

获取特定设备详情

端点： GET /api/v1/devices/{serial}

通过设备序列号获取特定设备的详细信息。

用户设备控制接口

添加设备到用户控制

端点： POST /api/v1/user/devices

此接口相当于在Web界面点击"Use"按钮，将设备添加到当前用户控制下。

请求示例：

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

远程连接设备

端点： POST /api/v1/user/devices/{serial}/remoteConnect

获取设备的远程调试URL，支持通过adb connect进行连接。

群组管理接口

STF支持设备群组管理，可以创建、更新和删除设备群组。

创建群组

端点： POST /api/v1/groups

创建一个新的设备群组，当前用户作为群组所有者。

实际应用场景

自动化测试集成

通过STF API，可以将设备管理功能集成到CI/CD流水线中，实现自动化测试的设备分配和释放。

典型工作流程：

1. 通过API获取可用设备列表
2. 预约目标设备
3. 获取远程连接地址
4. 执行自动化测试
5. 释放设备资源

多设备并发测试

STF支持同时控制多台设备，适合进行兼容性测试和性能对比测试。

最佳实践指南

错误处理

STF API返回标准HTTP状态码，常见的错误状态包括：

• 401 Unauthorized：认证失败
• 404 Not Found：资源不存在
• 500 Internal Server Error：服务器内部错误

性能优化建议

• 使用字段过滤减少响应数据量
• 合理设置设备使用超时时间
• 及时释放不再使用的设备资源

开发工具与SDK

Swagger客户端

STF API支持通过Swagger客户端进行调用，支持多种编程语言：

Node.js示例：

var Swagger = require('swagger-client');
var client = new Swagger({
  url: 'https://stf.example.org/api/v1/swagger.json',
  authorizations: {
    accessTokenAuth: new Swagger.ApiKeyAuthorization(
      'Authorization', 
      'Bearer ' + ACCESS_TOKEN, 
      'header'
    )
  }
});

client.then(function(api) {
  api.devices.getDevices().then(function(res) {
    console.log(res.obj.devices.length); // 设备数量
  });
});

总结

STF API提供了一套完整的设备管理解决方案，通过RESTful接口简化了移动设备的管理流程。无论是进行自动化测试、远程调试还是批量设备管理，STF API都能提供强大的支持。🚀

通过本文的详细解析，您应该已经掌握了STF API的核心功能和实际应用方法。现在就开始使用STF API，提升您的移动应用测试效率！

【免费下载链接】stf 项目地址: https://gitcode.com/gh_mirrors/stf/stf