TVS文档
此方案不再开放，新方案见：https://doc-bot.tmall.com/docs/doc.htm?spm=0.7629140.0.0.55dc1780u4Ph1I&treeId=566&articleId=118044&docType=1
要使用天猫精灵语音服务 (TmallGenie Voice Service; TVS)，你的精灵设备需要先取得 精灵access token ，并在每一次对TVS的请求之中都附上此token以进行授权验证。如果你的设备是没有任何图形化界面的，那用户的登录与授权操作必须要在与设备对应的app中进行相关操作以取得此token。本文将说明该如何进行取得精灵access token的操作与流程。
准备工作
目前天猫精灵语音服务尚未完全对外开放，大部分的应用创建、权限申请等工作需要由天猫精灵窗口人员协助于线下完成。
1. 淘宝开放平台开发者帐户
首先需要准备一个经过支付宝实名认证的淘宝帐户，并以此淘宝帐号登录淘宝开放平台申请成为开发者。
淘宝帐户与支付宝帐户的绑定可以在淘宝官网的帐号管理中的支付宝绑定设置页面中完成。
2. 创建淘宝开放平台应用
成为淘宝开放平台开发者后，请提供以下信息给天猫精灵同学:
- 淘宝开放平台开发者会员名
- 欲建立的应用名称 注意: 应用名称中不可包含 阿里 、 淘宝 、 天猫 等阿里巴巴品牌关键字
- 回调地址 (即OAuth2.0流程中会使用到的
redirect_uri地址。若无回调地址可先填写open.taobao.com，后续可随时在开放平台控制台中变更)
约0.5到1个工作天内天猫精灵同学会协助完成应用的建立。在收到天猫精灵同学的回复后，可在淘宝开放平台控制台页面看到该新建立的应用。
3. 申请天猫精灵语音服务API使用权限
进入应用详情页，可以看到关于此应用的重要信息，包含: app key、app secret以及可以使用的API权限包等。此时请将该应用的识别码 (即app key) 告知天猫精灵窗口，协助申请 天猫精灵语音服务 (TVS) API 权限包。完成申请后，可以在应用详情页的 功能场景 表格中看到此应用已获得 天猫精灵语音服务 (TVS) API 权限。此时可开始进行实际的登录流程开发工作。
精灵token取得流程
- 首先，厂商与设备协同交互的app应先取得关于要激活天猫精灵功能设备的设备元数据信息。
- 设备返回元数据，包含产品设备本身的标识信息 (product ID)，以及对于个别设备的识别序号 (Device Serial Number; DSN)。
- 用户点击集成在app的淘宝登录按钮，app切换至淘宝登录页，登录流程应该遵从用户授权介绍中的说明，需要的信息包括:
client_id: 创建TOP应用时获得的app key。client_secret: 创建TOP应用时获得的app key所对应的app secret。redirect_uri: 用户完成授权后会跳转过去的页面位址，应与创建应用时所注册的回调地址相同。
- 无线端接入淘宝授权有两种方式：1，淘宝授权SDK；2，淘宝H5授权。
- 在用戶完成淘宝登录后，淘宝登录服务返回授权码 (authorization code) 给app。
- App此时以此授权码、client ID (即app key)与redirect URI再向淘宝OAuth服务换取refresh token与access token。至此为止都是标准的OAuth授权流程，此步骤用户所授权取得的access token可用于调用前述 天猫精灵语音服务 (TVS) API 权限包中的API接口。
- 后文简称此处取得的token为 淘宝token 。
- 淘宝OAuth服务返回refresh token与access token。
- App将access token下发给自身对应的服务端以进行后续操作。
- 接著透过服务端调用 天猫精灵语音服务 (TVS) API 权限包中的
alibaba.ailabs.tvs.genietoken.get(DSN)接口，激活设备并取得之后用以访问TVS API的精灵服务access token，之后用户可以在天猫精灵app的”我的“页面上看到新创建的设备。- 后文简称此处取得的token为 精灵token 。
- DSN全名为Device Serial Number，即应由厂商所提供的对于同一产品的唯一设备标识序号，所取得的精灵token将与其所激活的设备一一对应。
- 返回精灵token。
- 服务端在返回精灵token予设备端。
- 建构TVS请求并带上精灵token以调用TVS服务。
- 透过淘宝token可以访问 天猫精灵语音服务 (TVS) API 权限包中的其他API。包含:
- alibaba.ailabs.tvs.device.list 以取得该淘宝帐户下已激活的TVS设备。
- alibaba.ailabs.tvs.device.get 以取得某台已激活TVS设备的详情。
- alibaba.ailabs.tvs.device.unregister 解绑某台TVS设备。
取得精灵token
上述最关键的一步在于需要用户在完成淘宝授权取得淘宝token，使用精灵服务所提供的接口换取精灵token。换取精灵token的接口 alibaba.ailabs.tvs.genietoken.get() 透过淘宝开放平台 (Taobao Open Platform; 简称TOP) 进行开放。因此需要使用TOP的API访问方式来进行调用，相关说明可见API调用方法详解与SDK使用说明等文档。
以下是取得精灵token的示例代码:
// 所使用的TOP URL endpoint依环境而有区别 // 1. 沙箱环境: https://gw.api.tbsandbox.com/router/rest // 2. 正式环境: https://eco.taobao.com/router/rest String url = "https://eco.taobao.com/router/rest"; String appkey = "25712328"; String secret = "dc7b472d123abc7894a7c58bf3e3d1e1b0"; TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret); String dsn = "abc-123-xyz-789" AlibabaAilabsTvsGenietokenGetRequest req = new AlibabaAilabsTvsGenietokenGetRequest(); req.setDsn(dsn); AlibabaAilabsTvsGenietokenGetResponse resp = client.execute(req); System.out.println(resp.getBody());
以上代码的执行结果应该类似于:
{
"alibaba_ailabs_tvs_genietoken_get_response": {
"status_code": "OK",
"is_success": true,
"expires_in": 1551774157,
"access_token": "URdJTwpyMSkjDHp0.......PAMxGjQtUyAeN1A0Pg"
}
}
回复报文中的 access_token 即为所取得的精灵token，需附在每一个TVS事件的 Authorization 标头中以进行效验。
Mock Token
为了方便目前正在联调测试的厂商或开发者进行调适，可以使用以下mock token先进行接口的测试与验证:
URdJTwpyMSkjDHp0RX56UVopIBZVPAMxGjQtUyAeN1A0PgxLKzshc1RiKBs5bTwBDT9RKzAyKT8cKxMdAyg4MSUiKTk2ZlFmYCwXKwAyNA4ebWlBAXELOzcmJwYOIQwQITQANzAydg8HDAQKBTVcVGU1PARGCB1MPiQCJxw2NTI7NiIcNCQ1Ew4xIQRkfBRwICMSVR8gOBBKeGNAVX8EDiQzMVdUCj0QNANEPEBuOiI7PStbUn91flw5LW48PzIVUyISRhwkHw0eOFoACicAIyUqVQhedG02JA5/PgsmFmRvZXh8aCc8Ch4kKDxtLC4ONyUfSEwvLg5DNQgWXmBRHDk0WlgAPRpSVygcMwUmIDwoKSYjISYEMS4iaGdbVydCPHAuUzEfe0p4cXJwLTANK1QsIRMnNAdXCwk/bQY6PCg4PQRva340BwV0GV4SHFQCGCAwICEhFFxfNjIfJyksBDdyQEthJj0/SSYEMzZqf05yfHNSEicNKzQiODkQAycKDSUZVkkHFwYBFhsUFQkKCkpcCEJMWlcUTwATEB9CDA0WVkdXBFFbUFUBTlZEEGMCR15bZFwaSAMLWw5VU19XVlE4RFIBVEE/RQgOWVlQV0wWSl1QBQtOVw==
设备解绑
调用alibaba.ailabs.tvs.device.unregister接口即可完成TVS设备解绑。
