JS API & REST API 快速入门

前言

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

JS API 和 REST API 综述

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

  • JS API
    • Total Control 脚本采用 JavaScript 语言编写，任何文本编辑工具，例如记事本，都可以用于开发 Total Control 脚本。
  • REST API
    • Total Control REST API 采用RESTful Web 服务框架设计，基于原有的 Total Control JS API 开发，支持任意脚本语言：如 Java, Node JS, Python, Ruby, C/C++ 等。支持各类操作系统：Android, iOS, Windows, macOS。

设备对象

当 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:

  • Device.closeApp(packageName)
  • http://IP:8090/TotalControl/v1/devices/:device/apps/:packageName
    请求方法：POST

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

  • 对单设备操作，url格式为：
    • “http://IP:8090/TotalControl/v1/devices/device=:device?token=:token”
  • 对多设备操作，url格式为：
    • “http://IP:8090/TotalControl/v1/devices/ids? token=:token&ids=:ids”，其中ids的格式为：ids=["device@1116106541","device@1116106541"]。

例如，在设备中对焦点输入框进行文字输入，其中，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.'}

TCHelp