JS API & REST API 快速入门

前言

在介绍本节内容之前,让我们先做一点准备工作,即在我们官网上下载并安装 Total Control软件

JS API 和 REST API 综述

JS API 和 REST API 是 Total Control 提供一系列脚本自动化接口,通过这些接口,可以对一个设备或多个设备操作。

设备对象

当 Total Control 软件连接设备时(单击”连接”按钮或自动连接),将创建一个对象,该对象包含所有与设备相关的属性和功能,以执行对设备的操作/输入。一旦设备断开连接,对象将被销毁,每一个设备一个对象,设备的对象标识为设备 ID,设备 ID 格式为 “device@ <10位数字>”。

JS API详解

脚本需要设备 ID 来对设备执行查询或操作,Device.searchObject()提供了获取单个设备 ID 或多个设备 ID 的各种方法。有关与设备 ID 关联的属性,请参阅 JS API 手册REST API 手册,有两种类型的功能:

设备 ID 是一个字符串,设备列表是一个数组。JS API 对单个设备操作使用 “device.” 或对设备列表操作用 “devices.”(可以同时执行多个设备)。对设备属性获取使用 “device. ”,注意,这些属性值都是对应的手机设备的真实属性,为只读,不可更改,因为每一台手机设备的属性有可能是不一样的,所以设备属性值仅针对单个设备对象。例如,

var device = Device.getMain();  //获取当前主控设备对象
var devices = Device.searchObject(sigmaConst.DevAll); //获取当前连接的所有设备

 //对设备操作
device.click(0.100, 0.100);          // 在主设备上点击相对坐标0.100, 0.100
devices.click(0.100, 0.100);         // 在所有连接的设备上点击坐标0.100, 0.100

//获取设备属性值
device.IP;     // 设备的IP地址
device.DPI;   // 设备屏幕的像素尺寸
device.IMEI;  // 设备的 IMEI 号    

REST API 详解

大部分 JS API 都有与其对应的 REST API,所以我们可以用两种不同的接口对单个或多个设备操作。更多接口请参见

例如,关闭指定包名的 app 的 JS API 和与其对应的 REST API:

REST API 地址以” http://IP:8090/TotalControl/v1/devices”开头,要获得设备对象,得先获得 Total Control 脚本开发所用的开发 token(REST API 认证机制,请求方式:GET, http://IP:8090/TotalControl/v1/login),再是获得设备对象,最后是对设备对象操作。

例如,在设备中对焦点输入框进行文字输入,其中,text 为输入的文字内容

//对单设备操作
http://IP:8090/TotalControl/v1/devices/device=:device/screen/texts
{
"token":"270eq7lXQK8bXYsJ",
"text":"33333",
}
//对多设备操作
http://IP:8090/TotalControl/v1/devices/ids/screen/texts
{
"token":"270eq7lXQK8bXYsJ",
"text":"33333",
"ids":["device@1116106541","device@1116106541"]
}


JS 和 REST API 获取设备对象的方法

我们可以用多种方法获取手机这个设备对象,既可以获得单个设备对象,也可以获得设备对象集合。

下面我们介绍JS API与其相对应的 REST API获取设备对象的几种方法,不是所有的 JS API 获取设备对象都有相对应的 REST API(REST API 获取设备对象的请求方法 GET):

//(单设备)获取当前主控设备对象
Device.getMain()
http://IP:8090/TotalControl/v1/devices/main?token=:token
//(单设备)通过给定的设备名称获取设备对象
Device.searchObject()
http://IP:8090/TotalControl/v1/devices?name=:name&token=:token
//(单设备)通过给定的设备序列号获取设备对象
Device.searchObject(sigmaConst.DevSerial,)
//(多设备)获取当前连接Total Control的所有设备的对象集合
Device.searchObject(sigmaConst.DevAll)
http://IP:8090/TotalControl/v1/devices?q=all&token=:token
//(多设备)根据给定的组名称获取组内所有设备的对象集合
Device.searchObject(sigmaConst.DevGroup, )
http://IP:8090/TotalControl/v1/devices?q=group&name=:name&token=:token
//(单设备)运行脚本后,弹出一个设备选择框,根据选择的一个设备进行设备对象获取
Device.searchObject(sigmaConst.DevSelectOne)
//(多设备)运行脚本后,弹出一个设备选择框,根据选择的多个设备进行设备对象集合获取
Device.searchObject(sigmaConst.DevSelectMult)
//(多设备)运行脚本后,弹出一个设备组选择窗口,根据选择的一个设备组获取组内所有设备的对象集合
Device.searchObject(sigmaConst.DevSelectGroup)


如何使用REST API

这里用Total Control JS API “TCHttpRequest”来解释怎么使用REST API,更多TCHttpRequest接口信息请看JS API手册,REST API对设备操作的步骤如下:

1. Base64编码用户名和密码

打开Total Control软件,在系统设置的REST API栏中找到REST API的账户信息(如下图所示),当然这里的用户名和密码也可以根据个人喜好改成其他的,用户名和密码用于token建立连接,获取token需要将用户名密码按照Base64编码。

将用户名和密码(username:password)组装进行 base64 编码生成字符串。 用户可以根据自己的代码语言,用其提供的方法将用户名和密码按照Base64编码。也可以用这个工具,http://tool.oschina.net/encrypt?type=3,在明文处输入” sigma:3D391497”点击BASE64编码,就可以获得BASE64编码值” c2lnbWE6M0QzOTE0OTc=”。

2. 获取 Total Control 脚本开发所用的开发 token

请求方式:GET

http://IP:8090/TotalControl/v1/login

//这里的“c2lnbWE6M0QzOTE0OTc=”是步骤一获得的BASE64编码值
var res = TCHttpRequest("http://localhost:8090/TotalControl/v1/login","GET",{Authorization:" c2lnbWE6M0QzOTE0OTc="},"",2000);
//用content来输出内容
 print(res.content);	

返回结果

//获得的token值就是" OEPux5xceiyIGO6r"
{"status":true,"value":{"token":" OEPux5xceiyIGO6r"}}

3. REST API 获取设备对象

REST API获取设备对象有很多种方法,请求方式GET,请看文章“获取设备对象方法”栏,这里的token就是第二步获取的token值" OEPux5xceiyIGO6r",IP就是IP地址。

//获取当前主控设备对象,返回值:设备对象,{"id":"device@-230441652"},对应的JS API 是Device.getMain()
TCHttpRequest("http://IP:8090/TotalControl/v1/devices/main?token=:token","GET",{},"",2000);


4. REST API 操作设备对象

对坐标(100,200)发送点击事件,请求方式POST,这里的device是步骤3获得的值,token是步骤2获得的值,x,y是这个REST API需要填的坐标值,state表示点击(按下+弹起)

//发送点击事件,对应的JS API 是device.click(x, y, state);
http://IP:8090/TotalControl/v1/devices/device@-230441652/screen/inputs
{
    "token":"270eq7lXQK8bXYsJ",
    "x":100,
    "y":200,
    "state":"press"
}


JS API接口使用示例

JS API实现打开手机上的QQ音乐软件

//获取设备对象device
var device = Device.getMain();
//用runApp(AppName) 打开QQ音乐
var runapp=device.runApp("com.tencent.qqmusic");
if (runapp == 0){
    print("成功打开QQ音乐软件");
} else{
    print(lastError());
}


运行结果

//当成功打开手机上的QQ音乐软件,则输出:
成功打开QQ音乐软件
//当打开QQ音乐软件失败,则输出错误信息


REST API接口使用示例

REST API实现打开手机上的QQ音乐软件

#!/user/bin/python
#-*- coding:utf-8 -*-

import urllib.parse
import urllib
import http.client
import json
import urllib.parse
import base64
import time
from argparse import Namespace

#定义一些基本的变量
REST_CONN = 'localhost:8090'
REST_BASIC_PATH = 'http://' + REST_CONN + '/TotalControl/v1/'
conn = http.client.HTTPConnection(REST_CONN)
user_pass = 'sigma:3D391497'

#定义获取token方法
#请求方式:GET,http://IP:8090/TotalControl/v1/login 
def login(conn,key):
    request_url = REST_BASIC_PATH + "login"
    header = {'Authorization':key}
    conn.request(method="GET", url=request_url, headers=header)
    response = conn.getresponse()
    res = response.readline()
    return res
#定义获取设备对象方法
#请求方式:GET,http://IP:8090/TotalControl/v1/devices/main 
def getMain(conn,token):
    request_url = REST_BASIC_PATH + "devices/main?token="+token
    conn.request(method="GET", url=request_url)
    response = conn.getresponse()
    res = response.readline()
    resp = json.loads(res)
    main = resp['id']
    return main
#定义打开软件的方法
#请求方式:POST,http://IP:8090/TotalControl/v1/devices/:device/apps/:packageName 
def runApp(conn,deviceId,appName,state,token):
    request_url = REST_BASIC_PATH + "devices/" + deviceId + "/apps/" + appName
    body={'state':state,'token':token}
    body=json.dumps(body).encode(encoding='utf-8')
    conn.request(method="POST",url=request_url,body=body)
    response = conn.getresponse()
    res = response.readline()
    return res

print("第一步: Base64编码用户名和密码")
encodeStr=base64.b64encode(user_pass.encode("UTF-8"))
print("Base64编码后的值为: " ,encodeStr)
print("第二步: 获取token")
#json.loads 用于解码 JSON 数据
res=login(conn,encodeStr)
resp = json.loads(res)
token=resp['value']['token']
print("获取到的token为:",token)
print("第三步: 获取设备对象")
deviceId=getMain(conn,token)
print("获取到的设备对象为:",deviceId)
print("第四步: 打开QQ音乐软件")
ret = runApp(conn,deviceId,"com.tencent.qqmusic","active",token)
ret_json = json.loads(ret)
print(ret_json)
#休眠五秒
time.sleep(5)


运行结果

第一步: Base64编码用户名和密码
Base64编码后的值为:  b'c2lnbWE6M0QzOTE0OTc='
第二步: 获取token
获取到的token为: cSb8XU8JQAk85X7d
第三步: 获取设备对象
获取到的设备对象为: device@-230441652
第四步: 打开QQ音乐软件
{'status': True, 'value': 'make it active.'}