Skip to content

Latest commit

 

History

History
284 lines (222 loc) · 6.9 KB

API.md

File metadata and controls

284 lines (222 loc) · 6.9 KB
Raw

atxserver2 API文档

设备占用接口参考了openstf的API

其中$SERVER_URL代表atxserver2的地址，如http://localhost:4000

所有的接口采用token认证，每个请求在 Header中增加 Authorization: Bearer xxxxx-token-xxxx

token可以在 $SERVER_URL/user 界面获取到

获取到token后，可以先做一个小的尝试。假设token被保存到了$TOKEN这个环境变量中

$ pip install httpie # 安装http命令行工具
$ http GET $SERVER_URL/api/v1/user Authorization:"Bearer $TOKEN"
{
    "username": "fa",
    ....
}

如果Token填写错误，服务器响应403 Forbidden

下面的一些操作也都是用httpie这个小工具做的演示，使用方法见httpie cheetsheet

获取用户信息

GET /api/v1/user

$ http GET $SERVER_URL/api/v1/user
{
    "email": "[email protected]",
    "username": "fa",
    "token": "xxxxx.....xxxxx",
    "createdAt": "2019-03-06T12:38:02.338000",
    ...
}

获取设备列表

GET /api/v1/devices

$ HTTP GET $SERVER_URL/api/v1/devices
# 支持的过滤参数 ?platform=apple&usable=true

{
    "success": true,
    "devices": [{
        "platform": "android",
        "present": true,
        "using": true,
        "colding": false,
        "userId": "[email protected]",
        "properties": {
            "brand": "SMARTISAN",
            "version": "7.1.1"
        },
        ....
    }],
    "count": 4,
}

几个比较重要的字段说明

  • platform目前有两个值android和apple
  • present代表设备是否在线
  • colding代表设备是否正在清理或者自检中, 此时是不能占用设备的
  • using代表设备是否有人正在使用
  • userId代表使用者的ID，这里的ID其实就是Email
  • properties代表设备的一些状态信息，基本都是静态信息

usable等价于{present: true, using: false, colding: false}

获取单个设备信息（不包含sources字段)

GET /api/v1/devices

$ HTTP GET $SERVER_URL/api/v1/devices/${udid}
{
    "success": true,
    "device": {
        "udid": "6EB0217704000486",
        "platform": "android",
        "present": true,
        "using": false,
        "colding": false,
        "userId": null,
        "properties": {
            "brand": "HONOR",
            "model": "DUK-AL20",
            "name": "华为 荣耀 V9",
            "serial": "6EB0217704000486",
            "version": "8.0.0"
        },
        "updatedAt": "2019-03-29T14:53:56.569000",
        "usingBeganAt": "2019-03-28T18:33:23.100000"
    }
}

If udid not found, status code = 400

占用设备

POST /api/v1/user/devices

$ http POST $SERVER_URL/api/v1/user/devices <<< '{"udid": "xx...xxxx"}'

{
    "success": true,
    "description": "Device successfully added"
}

通过payload传递数据，JSON格式

  • udid是必须字段(Android设备的udid是设备的product，mac地址，serial组合生成的)
  • idleTimeout: 设备最长空闲时间 seconds(可选), 当前时间 - 活动时间 > idleTimeout 自动释放设备
{
    "udid": "xlj1311l2fkjkzdf",
    "idleTimeout": 600
}

如果你是管理员，你还可以传email将设备占用人指定为其他人。

{
    "udid": "xlj1311l2fkjkzdf",
    "email": "[email protected]"
}

更新活动时间接口

GET /api/v1/user/devices/{$UDID}/active

$ http GET /api/v1/user/devices/${UDID}/active
{
    "success": true,
    "description": "Device activated time updated"
}

获取用户设备信息(包含source字段)

GET /api/v1/user/devices/${UDID}

$ http GET $SERVER_URL/api/v1/user/devices/${UDID}

{
    "success": true,
    "device": {
        "platform": "android",
        "present": true,
        "using": true,
        "colding": false,
        "userId": "[email protected]",
        "properties": {
            "brand": "SMARTISAN",
            "version": "7.1.1"
        },
        "source": {
            "atxAgentAddress": "10.0.0.1:20001",
            "remoteConnectAddress": "10.0.0.1:20002",
            "whatsInputAddress": "10.0.0.1:20003",
            "secret": "6NC5Tls1",
            "url": "http://10.0.1.1:3500",
        }
    }
}

比 /api/v1/devices 获取到的设备，多出一个source字段，下面详细说明下

Android和iOS source都包含的部分

  • url: provider的URL，通过可以让设备cold和安装应用

Android的source独有内容

  • atxAgentAddress: 主要用于uiautomator2测试框架
  • remoteConnectAddress: 用于adb connect连接使用
  • whatsInputAddress: 这个可以不用关注，他主要提供远程真机的实时输入法

iOS的source独有内容

  • wdaUrl: webdriveragent用到的http接口，eg http://10.0.0.1:9300

WebSocket访问${wdaUrl}/screen可以获取到当前的图片流

释放设备

DELETE /api/v1/user/devices/${UDID}

$ http DELETE $SERVER_URL/api/v1/user/devices/xxx...xxx

{
    "success": true,
    "description": "Device successfully released"
}

APK上传与解析(TODO)

POST /uploads

$ http POST $SERVER_URL/uploads [email protected]
HTTP/1.1 200 OK
Content-Length: 411
Content-Type: application/json; charset=UTF-8
Date: Wed, 23 Jan 2019 06:28:54 GMT
Server: TornadoServer/4.5.3

{
    "data": {
        "url": "http://localhost:4000/uploads/13/f46364434b526b77620ebf9bcf7322/com.doublep.wakey.apk",
        "md5sum": "13f46364434b526b77620ebf9bcf7322",
        "iconPath": "res/drawable-xxhdpi/ic_launcher.png",
        "iconUrl": "http://localhost:4000/uploads/13/f46364434b526b77620ebf9bcf7322/icon.png",
        "packageName": "com.doublep.wakey",
        "mainActivity": ".Bulb",
        "versionCode": "18",
        "versionName": "2.3"
    },
    "success": true
}

通过PROVIDER进行APK安装

这个要用到PROVIDER_URL对应设备信息接口返回值中的source.url字段,另外需要指定udid（因为provider可能连接了多个手机）

POST $PROVIDER_URL/app/install?udid=xxxx

$ http --form POST $PROVIDER_URL/app/install?udid=xxxx url==http://example.com/some.apk launch==true
# launch是可选参数，代表是否安装成功后启动应用
# 成功返回 200
{
    "success": true
    "return": 0,
    "output": "Success\r\n",
    "packageName": "io.appium.android.apis",
}
# 失败返回 400 or 500
{
    "description": "Failure reason",
    "success": false
}

通过PROVIDER进行IPA安装

这个要用到PROVIDER_URL对应设备信息接口返回值中的source.url字段,另外需要指定udid（因为provider可能连接了多个手机）

POST $PROVIDER_URL/app/install?udid=xxxx

$ http --form POST $PROVIDER_URL/app/install?udid=xxxx url==http://example.com/some.ipa
# 成功返回 200
{
    "success": true
    "return": 0,
    "output": "Success",
}
# 失败返回 400 or 500
{
    "description": "Failure reason",
    "success": false
}