[关闭]
@miniknife 2017-07-12T04:25:18.000000Z 字数 9899 阅读 26280

TS Remote API 触动精灵远程接口开发手册

开发手册 API文档


当前手册适用于触动精灵 iOS v2.2.3+,Android v1.3.0+ 版本

目录

简介

触动精灵为高级开发者提供部分开放 API 接口,使用此接口可为触动精灵开发周边扩展工具,实现诸如:远程启动脚本、远程停止脚本、获取脚本运行状态、发送文件等功能,接口调用需验证开发者身份,请注册登录触动精灵开发者平台申请。

使用须知

  • 大部分接口需要触动精灵 iOS 客户端授权后方可正常使用,调试前请确保您用来调试的设备已经购买过触动精灵授权并激活
  • 此接口同样适用于触动精灵安卓客户端,且安卓无需购买客户端授权
  • 本接口仅适用于触动精灵(非企业版)和触动小精灵
  • 本手册仅提供接口信息,各位开发者可使用自己熟悉的任意语言进行编程(包括但不限于 C、Java 和易语言)

价格与购买

数量(台) 价格(元/月) 价格(元/年)
5 免费 免费
50 50 500
100 100 1000
200 200 2000
1000 300 3000

注意事项

  • 接口购买地址:http://dev.touchsprite.com/openapi/index?handle-type=add_access_key
  • 每个开发者账号会提供一个免费的试用 key,允许 5 台设备进行调试
  • 当使用该 key 的设备到达最大上限时,可以通过清空设备列表取消之前的设备的授权,再添加新设备
  • 如果您付款成功却没有显示 Access Key,请联系客服 QQ 2885667299 提供您的购买记录、商户订单号和开发者邮箱进行查询

功能介绍

获取身份验证

入口地址: https://storeauth.touchsprite.com/api/openapi(本网址仅为入口,不可使用浏览器直接访问)
参数格式: JSON
请求方式: POST

客户端发送

  1. {
  2. "action": "getAuth", //获取验证串
  3. "key": "开发者的key", //开发者的 access key
  4. "devices": ["设备号1","设备号2"...], //设备数量不能超过开发者的最大设备数限制
  5. "valid": 希望验证串的有效期, //单位秒,最大为 3600
  6. "time": 时间戳 //当前 Unix 时间戳
  7. }

服务器正确返回

  1. {
  2. "status": 200, //200成功
  3. "message":"xx", //status不等于 200 时,返回错误提示。
  4. "time": 1422930265, //当前 Unix 时间戳
  5. "auth": "xx", //验证串,直接填充到发送给触动服务的 auth 字段
  6. "valid": 3600, //验证串实际有效时间
  7. "remainder_token": 4 //剩余的令牌数,当剩余令牌为 0 时,getAuth 协议将调用失败
  8. }

注意事项:

  1. 入口请求地址只支持这个域名的HTTPS

局域网广播

  • 在搜索设备时,先建立一个 UDP 接收端,然后发送一个包含自己 IP 地址和端口信息的广播
  • 广播的端口号为 14099,UDP 接收端就会收到来自各方触动客户端的回复

是否需要验证:否

控制端需要发送信息

  1. {"ip":"接收端IP", "port":接收端端口号}

各方触动正确返回

  1. {"deviceid":"设备号", "tsversion":"触动版本号", "ip":"该设备IP", "port":设备服务端口, "devname":"设备名"}

协议框架

远程调用服务采用 HTTP 框架,部分协议需要验证调用者身份

控制客户端调用格式

  1. http方法:[POST或者GET] /[命令路径] HTTP/1.1
  2. Host: [服务端ip]
  3. Connection: close
  4. Content-Length: [数据长度]
  5. 其他参数: [header]

LUA调用实例

  1. local response_body = {}
  2. http = require("socket.http")
  3. http.TIMEOUT=1
  4. local response_body = {}
  5. local rep , code = http.request{
  6. url = "http://192.168.0.2:50005/status",
  7. headers=
  8. {
  9. ["auth"] = Auth,
  10. },
  11. sink = ltn12.sink.table(response_body),
  12. }

注意事项:

Auth 通过 getAuth 方法获得,具体使用参照开发者后台 http://dev.touchsprite.com/openapi/index

获取触动精灵设备号

是否需要验证:否

控制客户端发送

  1. GET /deviceid HTTP/1.1
  2. Host: [服务端ip]
  3. Connection: close
  4. Content-Length: 0

服务返回

  1. HTTP/1.1 200 OK
  2. Connection: close
  3. [触动精灵设备号]

获取设备名

是否需要验证:否

控制客户端发送

  1. GET /devicename HTTP/1.1
  2. Host: [服务端ip]
  3. Connection: close
  4. Content-Length: 0

服务返回

  1. HTTP/1.1 200 OK
  2. Connection: close
  3. [设备名]

远程截图

是否需要验证:是

控制客户端发送

  1. GET /snapshot?ext=[jpg|png]&compress=[0.1-1]&orient=[0|1|2|3] HTTP/1.1
  2. Host: [服务端ip]
  3. Auth: [验证串]
参数 说明
ext 截图格式
compress 当格式为JPG时有效,范围为 0.1 - 1
orient 图片方向,对应移动设备的四种方向

服务返回

  1. HTTP/1.0 200 OK
  2. Content-Length: [图片长度]
  3. Content-Type: image/png
  4. [图片数据]

上传文件

是否需要验证:是

控制客户端发送

  1. POST /upload HTTP/1.1
  2. Host: [服务端ip]
  3. auth: [验证串]
  4. root: [根类型:lua|res|log|plugin]
  5. path: [路径:例如"/aaa"或者"/aaa/bbb";多级路径下,前面带'/';后面不带‘/’,根路径就是"/"]
  6. filename: [文件名]
  7. Connection: close
  8. Content-Type: touchsprite/uploadfile
  9. Content-Length: [文件长度]
  10. [文件数据]

服务返回

  1. HTTP/1.0 200 OK
  2. Content-Length: 2
  3. Content-Type: text/html; charset=utf-8
  4. [ok|fail]

HTTP返回代码含义

返回代码 代码含义
200 成功
400 参数错误
401 授权验证失败

远程日志

是否需要验证:是

控制客户端发送

  1. GET /logServer HTTP/1.1
  2. Server: [LOG服务ip]
  3. Auth: [验证串]
  4. Port: [端口号]

服务返回

  1. HTTP/1.0 200 OK
  2. Content-Length: 2
  3. Content-Type: text/html; charset=utf-8
  4. [ok|fail]

HTTP返回代码含义

返回代码 代码含义
200 成功

获取脚本运行状态

是否需要验证:是
控制客户端发送

  1. GET /status HTTP/1.1
  2. Auth: [验证串]

服务返回

  1. HTTP/1.0 200 OK
  2. Content-Length: 3
  3. Content-Type: text/html; charset=utf-8
  4. [f00|f01|f02]

名词解析:

f00 - 空闲;f01 - 运行;f02 - 录制

HTTP返回代码含义

返回代码 代码含义
200 成功

获取设备目录文件列表

是否需要验证:是

控制客户端发送

  1. GET /getFileList HTTP/1.1
  2. Auth: [验证串]
  3. Root: [根类型:lua|res|log|plugin]
  4. Path: [路径:例如"/aaa"或者"/aaa/bbb";多级路径下,前面带'/';后面不带‘/’,根路径就是"/"]

服务返回

  1. HTTP/1.0 200 OK
  2. Content-Length: 143
  3. Content-Type: text/html; charset=utf-8
  4. {"ret":true,"Dirs":[],"Path":"\/","Files":["1436408889.lua","test.lua","main.ios.tsp","sz-ios.lua","sz-ios.lua.lua","ts1-ios.lua"],"Root":"lua"}
返回 说明
ret true - 成功;false - 失败
Dirs 文件夹数组
Files 文件数组
Path 子路径
Root 根路径

HTTP返回代码含义

返回代码 代码含义
200 成功

获取远程文件到本地

是否需要验证:是

控制客户端发送

  1. GET /getFile HTTP/1.1
  2. Host: [服务端ip]
  3. Auth: [验证串]
  4. Root: [根类型:lua|res|log|plugin]
  5. Path: [路径:例如"/aaa"或者"/aaa/bbb";多级路径下,前面带'/';后面不带‘/’,根路径就是"/"]
  6. file: [文件名]
  7. Connection: close

服务返回

  1. HTTP/1.0 200 OK
  2. Content-Length: [文件长度]
  3. Content-Type: text/html; charset=utf-8
  4. [文件数据]

HTTP返回代码含义

返回代码 代码含义
200 成功
400 参数错误
401 授权验证失败

重启设备

是否需要验证:是

控制客户端发送

  1. GET /reboot?type=1 HTTP/1.1
  2. Auth: [验证串]

服务返回

  1. HTTP/1.0 200 OK
  2. Content-Length: 2
  3. Content-Type: text/html; charset=utf-8
  4. [ok|fail]

HTTP返回代码含义

返回代码 代码含义
200 成功

注销设备

是否需要验证:是

控制客户端发送

  1. GET /reboot?type=0 HTTP/1.1
  2. Auth: [验证串]

服务返回

  1. HTTP/1.0 200 OK
  2. Content-Length: 2
  3. Content-Type: text/html; charset=utf-8
  4. [ok|fail]

HTTP返回代码含义

返回代码 代码含义
200 成功

设置远程运行脚本的路径

是否需要验证:是

控制客户端发送

  1. POST /setLuaPath HTTP/1.1
  2. Auth: [验证串]
  3. Content-Type: application/json
  4. Host: [服务端ip]
  5. Connection: close
  6. Content-Length: 46
  7. {"path":"/var/mobile/Media/TouchSprite/lua/test.lua"}

注意事项:
示例中的路径为触动精灵 iOS 版脚本路径,安卓路径请在手机触动精灵客户端更多界面查看设备信息获取。

服务返回

  1. HTTP/1.0 200 OK
  2. Content-Length: 2
  3. Content-Type: text/html; charset=utf-8
  4. [ok|fail]

HTTP返回代码含义

返回代码 代码含义
200 成功

远程运行脚本

是否需要验证:是

控制客户端发送

  1. GET /runLua HTTP/1.1
  2. Auth: [验证串]

服务返回

  1. HTTP/1.0 200 OK
  2. Content-Length: 2
  3. Content-Type: text/html; charset=utf-8
  4. [ok|fail]

HTTP返回代码含义

返回代码 代码含义
200 成功

停止远程运行

是否需要验证:是

控制客户端发送

  1. GET /stopLua HTTP/1.1
  2. Auth: [验证串]

服务返回

  1. HTTP/1.0 200 OK
  2. Content-Length: 2
  3. Content-Type: text/html; charset=utf-8
  4. [ok|fail]

HTTP返回代码含义

返回代码 代码含义
200 成功

删除远程设备文件

是否需要验证:是

控制客户端发送

  1. GET /rmFile HTTP/1.1
  2. Auth: [验证串]
  3. Root: [根类型:lua|res|log|plugin|config]
  4. Path: [路径:例如"/aaa"或者"/aaa/bbb";多级路径下,前面带'/';后面不带‘/’,根路径就是"/"]
  5. file: [文件名]
  6. Connection: close

服务返回

  1. HTTP/1.0 200 OK
  2. Content-Length: 2
  3. Content-Type: text/html; charset=utf-8
  4. [ok|fail]

HTTP返回代码含义

返回代码 代码含义
200 成功

设置远程设备分辨率

是否需要验证:是

控制客户端发送

  1. GET /setScreenRes HTTP/1.1
  2. Auth: [验证串]
  3. type: ["640x960"|"750x1334"|"640x1136"|"1125x2001"|"1242x2208"|"768x1024"|"1536x2048"|"default"]
  4. Connection: close

服务返回

  1. HTTP/1.0 200 OK
  2. Content-Length: 2
  3. Content-Type: text/html; charset=utf-8

HTTP返回代码含义

返回代码 代码含义
200 成功

示例代码

下面是用 lua 写的 API 示例,点击下载文件 TSRemoteAPIDemo.lua4.1kB
本代码由 天朝五毛君 分享。

  1. --[[测试环境 OsVer: ios7.0.1
  2. TsVer: v2.3.5
  3. 必备库 luaSocket
  4. 测试者: Half
  5. ]]
  6. local sz = require"sz"
  7. local http = require"szocket.http"
  8. local json = sz.json
  9. local ltn12 = require"ltn12"
  10. local response_body = {} -- 构造主体部位接受的地方
  11. local post_data = {
  12. action = "getAuth",
  13. key = "JqYVQgWc4V6dTVq部分马赛克处理掉7yKRbZDGYfg4Yp6F4qv0xjoU", -- 这就不用我自己的了……替换成自己的就好了
  14. devices = {"aab9d7903部分马赛克处理掉cc0c0f51b595b70"}, -- 设备ID
  15. time = os.time(),
  16. valid = 3600,
  17. }
  18. post_data = json.encode(post_data)
  19. local staus,code,header = http.request{
  20. url = "http://openapi.touchsprite.com/api/openapi",
  21. method = "POST",
  22. headers =
  23. {
  24. ["Content-Type"] = "application/x-www-form-urlencoded",
  25. ["Content-Length"] = #post_data,
  26. },
  27. source = ltn12.source.string(post_data),
  28. sink = ltn12.sink.table(response_body), --用ltn12转化接受的数据为lua可用
  29. }
  30. print(table.concat(response_body))
  31. --将会打印以下内容,这是一个json,将之使用json.decode处理后取auth字段保存起来供我们接下来使用
  32. --[[{"status":200,
  33. "auth":"直接马赛克好了,那么长的一串",这就是我们获取到的验证串,由于太长我就马赛克掉了
  34. "valid":2592000,"devices":["aab9d7903393a992dcc0c0f51b595b70"],
  35. "remainder_token":0,
  36. "time":1470216706}]]
  37. local auth = "eyJrZXkiOiJGSmRrNFdBQmY2WnByc0NFSG40ZzNUcmZZMDlBNk9HNXNcL0NiczNzblhzdTQ3NTczRDJ5dXFNN1wvdXFlRFwvMldCclZyU3hEbEdEb0owWUJtV1RpekV5OWlFMVdoNmpiZ0Y4dG5mWWwrY0hKSHBVTmtSOWx4QkxCQjVvOTN1WTZGMFwvRzEyODBxY09WQUtXazExVklqT1pQM3pRVzJzeUVMeDVvM200QzVYcitKQ3pxdmhqM2hjdWx1MXJCdjJkRUg0YTlGaWZtNmpERXUyU1NkajJqcWRYb0M2Y013eUZnb08rc1dqVUtNNUtqekZZN3pJc1IrVTZwM0R3MWZnQ2dSRVZCdUhpRFdyUGdCXC9HbXNLaVZoM1JGdzF6aWlwWEVJSnhtZ2VOeUFqNnlVSGp2K2lVVkVGTThzNkdVc05UMUN1ZmpHK0NGV3VyRjg4VTZSQlRKeGdhQT09IiwiZGF0YSI6IjN0TFhNVFRKRTJkdWZtUlFcL2tuTjlcL3Z4Qm8zOFhlT2t1WE1UUHVKSHMrYXRMdFc3YW96QzlFY3IwcFwvTVJGdlJFRDlcL3NaY3p6ellQRlI4aDJocmtyWjhjUzdSQ2F0ZDRLMHhNXC9zaGpXclNzQTd1NG5HaE5kdTMyeTQ1bm9TUXgiLCJtZDUiOiJQdHp0YXo5b1ZKalgzb29HcTRVczVuYWgyVVwvbkxKcXpFNkNHMWVXSnRPMFVpa2ZhNjFEa1RNZVNhZ0hSUlwvYlFtdThYWXlOQWY3RERhekJxSDZcL2ZIR0hObkhSYzhpeDVOWWo1Mmt1cERuK3VMb3BDUlM0Q0lKREdhbjZqd2VnRnUzQjdia0RQbERRYzRKRlpCNmpXc1B0emFkdGtWVUZvOWYxazFKNk1Qd3dGNUx2WHVsSDB1MTg1SVVCeHJyNnZBRXdhcVBxUTYxbUpVZFg5ZE5RWTR2UzVoalp1UU85bXpEd3d1UDhMblwvVVY1QnAxUmNVVmZqVFA4MThzTjRyTHhCZk9lMzBHR2pVYkR1SEhpUlwvVjhyVzZGN0RiYWpIYXBcL0lnbmJrN1wvYkJaU1NjTEF4dkNkajc2Y2EwSmlqNHJqOHZPRG0rcXFGeWVtMWJlcFV3VUhBPT0ifQ=="
  38. -- --假装保存了auth
  39. local response_body = {}
  40. http.TTIMEOUT = 8
  41. local staus,code,header = http.request{
  42. url = "http://192.168.1.120:50005/deviceid",
  43. headers =
  44. {
  45. ["Content-Type"] = "application/x-www-form-urlencoded",
  46. },
  47. sink = ltn12.sink.table(response_body), --用ltn12转化接受的数据为lua可用
  48. }
  49. print(table.concat(response_body))
  50. --将会打印[[aab9d7903393a马赛克以下c0c0f51b595b70]]
  51. local response_body = {}
  52. local staus,code,header = http.request{
  53. url = "http://192.168.1.120:50005/snapshot?exp=png&orient=0",
  54. headers =
  55. {
  56. ["Content-Type"] = "application/x-www-form-urlencoded",
  57. ["auth"] = auth,
  58. },
  59. sink = ltn12.sink.table(response_body), --用ltn12转化接受的数据为lua可用
  60. }
  61. local function writePicture(picpath, content)
  62. local file = io.open(picpath,"wb")
  63. if file then
  64. file:write(content)
  65. file:close()
  66. return true
  67. end
  68. return false
  69. end
  70. writePicture("C:\\Users\\Administrator\\Desktop\\1.png",table.concat(response_body))
  71. --在桌面写入一张图片
  72. local response_body = {}
  73. local staus,code,header = http.request{
  74. url = "http://192.168.1.120:50005/getFileList",
  75. headers =
  76. {
  77. ["Content-Type"] = "application/x-www-form-urlencoded",
  78. ["auth"] = auth,
  79. ["Root"] = "lua",
  80. ["Path"] = "/"
  81. },
  82. sink = ltn12.sink.table(response_body), --用ltn12转化接受的数据为lua可用
  83. }
  84. print(table.concat(response_body))
  85. --我的打印{"ret":true,"Dirs":[],"Path":"\/","Files":[".12786.cfg",".383.cfg",".8308.cfg","12786.tsp","1467787409.lua","383.tsp","8308.tsp","English.lua"]}

附录

触动精灵安卓Android脚本开发手册

https://www.zybuluo.com/miniknife/note/148136

触动精灵脚本开发函数扩展库

https://www.zybuluo.com/miniknife/note/293935

触动精灵iOS脚本开发视频教程

https://www.zybuluo.com/miniknife/note/307651

已知与触动精灵冲突的插件列表

showUI 不能弹出、点击没反应、滑动失效等问题有可能是由于安装了冲突插件引起的
https://www.zybuluo.com/miniknife/note/307651#已知与触动精灵冲突的插件列表

触动精灵脚本开发实例代码

https://www.zybuluo.com/miniknife/note/323513

下载、安装触动精灵iOS/帮你玩脚本商城,欢迎添加官方推荐软件源

触动精灵官方源:http://apt.touchsprite.com

触动精灵iOS使用教程

https://www.zybuluo.com/miniknife/note/307627

脚本编辑器

远程调试、运行脚本
1. TouchSprite Studio(v1.1.7):http://pan.baidu.com/s/1bn5b9Vp 密码:k9yf

取色、图像工具

远程截图、取色、生成代码
1. 触动精灵抓色工具(v1.7.8):http://bbs.touchsprite.com/question/5190

脚本加密

https://www.zybuluo.com/miniknife/note/307651#脚本加密

文字点阵识别字库制作工具

  1. 大漠:http://pan.baidu.com/s/1qXpdUw8 密码:ljay

设备 SSH 连接工具

  1. WinSCP:http://pan.baidu.com/s/1o6jtP7G
  2. 简体中文语言包:http://pan.baidu.com/s/15xaEy
  3. Putty:http://pan.baidu.com/s/1mgslwX6

相关工具运行库

  1. VCredist 2010:http://pan.baidu.com/s/1sjjTFQH
  2. NET Framework 4:http://www.microsoft.com/zh-cn/download/details.aspx?id=17718

OCR(光学字符识别)相关

  1. 触动精灵本地OCR简体中文识别库:http://pan.baidu.com/s/1qW2mDWC
  2. 触动精灵本地OCR英文数字识别库:http://pan.baidu.com/s/1eQ3nbZs
添加新批注
在作者公开此批注前,只有你和作者可见。
回复批注