天猫精灵开发接入方式和流程介绍

天猫精灵最新动态&学习交流

Written by:

1、概述

采用通用的OAuth2.0开放授权协议,可以让AliGenie在不获取合作方用户名和密码的前提下,访问用户授权的资源,协议规范可以访问OAuth2.0官方网站:https://oauth.net/2/

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进行访问合作方的服务

3、运行流程

OAuth 2.0的运行流程如下图

天猫精灵接入OAuth 2.0的运行流程如下图

天猫精灵接入OAuth 2.0的运行流程如下图

(A)用户打开客户端以后,客户端要求用户给予授权。

(B)用户同意给予客户端授权。

(C)客户端使用上一步获得的授权,向认证服务器申请令牌。

(D)认证服务器对客户端进行认证以后,确认无误,同意发放令牌。

(E)客户端使用令牌,向资源服务器申请获取资源。

(F)资源服务器确认令牌无误,同意向客户端开放资源。

4、AliGenie 开放平台oauth 基础配置

天猫精灵开放平台oauth 基础配置

天猫精灵开放平台oauth 基础配置

注意点:服务配置中请使用安全套接字层超文本传输协议HTTPS并且已经授信

5、请求API
(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 字段。

通过code换取access_token 响应结构如下(响应格式 application/json):

字段 类型 解释说明
access_token String 访问token(响应正确时必传递)
refresh_token String 进行刷新access_token的刷新token (响应正确时必传递)
expires_in long 过期时间时长(响应正确时必传递)
error String 错误响应码 (响应错误时必传递)
error_description String 错误详情 (响应错误时必传递)

正常响应:

{
  "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 响应结构如下(响应格式 application/json):

字段 类型 解释说明
access_token String 访问token(响应正确时必传递)
refresh_token String 进行刷新access_token的刷新token (响应正确时必传递)
expires_in long 过期时间时长(响应正确时必传递)
error String 错误响应码 (响应错误时必传递)
error_description String 错误详情 (响应错误时必传递)

正常响应:

{
  "access_token": "XXXXXX",
  "refresh_token": "XXXXXX"
  "expires_in":17600000
  }

错误响应:

{
  "error":"errorCode",
  "error_description":"description"
 }

注意事项:
1.获取access_token或者刷新access_token出现错误情况时http response status code 请返回200 ,接入方的内部异常请接入方自行包装异常信息

发表评论

电子邮件地址不会被公开。 必填项已用*标注