天猫精灵Aligenie对接记录（一）

天猫精灵Aligenie对接记录（一）

公司在开发一个智能家居相关的项目时要对接天猫精灵，分享一下相关经验，如果想深入交流或者有这方面的需求可以到

https://www.jksxit.com

第一步，创建技能，在Aligenie开发者平台的控制台创建技能并填写相关信息即可。

第二步，设置服务，则需要在自己平台建立Oauth2.0-Server服务，采用通用的OAuth2.0开放授权协议，可以让AliGenie在不获取合作方用户名和密码的前提下，访问用户授权的资源，协议规范可以访问OAuth2.0官方网站：https://oauth.net/2/

鉴权流程
（1）AliGenie在开发商开放平台或者其他第三方平台注册一个应用，获取到相应的Client id 和Client secret

（2）AliGenie 应用向开发商OAuth2.0服务发起一个授权请求

（3）开发商OAuth2.0服务向用户展示一个授权页面，用户可进行登陆授权

（4）用户授权AliGenie客户端应用后，进行回跳到AliGenie 的回调地址上并带上code相关参数

（5）AilGenie回调地址上根据code会去合作方Oauth 的服务上换取 access_token

（6）通过access_token，天猫精灵设备控制时通过该access_token进行访问合作方的服务

(A) 用户打开授权链接进行授权
例：
https://xxx.com/auth/authorize?redirect_uri=https%3A%2F%2Fopen.bot.tmall.com%2Foauth%2Fcallback%3FskillId%3D11111111%26token%3DXXXXXXXXXX&client_id=XXXXXXXXX&response_type=code&state=111

参数说明：
redirect_uri: AliGenie平台的回调地址，该地址会加上AliGenie的参数进行urlEncode,所以合作方务必做好参数返回的兼容性
client_id: 在合作方上注册的应用Id
response_type: 响应方式为code
state:表示客户端的当前状态，可以指定任意值，认证服务器会原封不动地返回这个值。

注：示例中的链接API(https://xxx.com/auth/authorize) 为开放平台中的账户授权链接字段。

(B) 通过code换取合作方访问令牌
例：
https://XXXXX/token?grant_type=authorization_code&client_id=XXXXX&client_secret=XXXXXX&code=XXXXXXXX&redirect_uri=https%3A%2F%2Fopen.bot.tmall.com%2Foauth%2Fcallback
请求方法： POST

参数说明：
client_id: 在合厂商平台上注册的应用Id
grant_type: 授权类型 authorization_code
client_secret:在厂商平台上注册应用的secret
code: 授权登陆后回调AliGenie的地址返回的code
redirect_uri: AliGenie回调地址

注：示例中的链接API ( https://XXXXX/token) 为开放平台中的Access Token Url 字段。2018年1月4日之后，创建的技能通过body来传参。

通过code换取access_token 响应结构如下
正常响应：
{
“access_token”: “XXXXXX”,
“refresh_token”: “XXXXXX”，
“expires_in”:17600000
}
错误响应：
{
“error”:“errorCode”,
“error_description”:“description”
}
注： access_token 有效期请设置成1天以上(2-3天最佳)

( C ) 通过refresh_token刷新access_token（该功能已上线，请确保厂商自己的刷新功能是完善的）
例：
https://XXXXX/token?grant_type=refresh_token&client_id=XXXXX&client_secret=XXXXXX&refresh_token=XXXXXX

请求方法： POST

参数说明：
grant_type：更新access_token的授权方式为refresh_token
client_id: 在厂商平台上注册的应用Id
client_secret:在厂商平台上注册应用的secret
refresh_token: 上一次授权获取的refresh_token

注：示例中的链接API( https://XXXXX/token) 为开放平台中的Access Token Url 字段。
正常响应：
{
“access_token”: “XXXXXX”,
“refresh_token”: “XXXXXX”，
“expires_in”:17600000
}
错误响应:
{
“error”:“errorCode”,
“error_description”:“description”
}
注意事项：
1.获取access_token或者刷新access_token出现错误情况时http response status code 请返回200 ，接入方的内部异常请接入方自行包装异常信息