楼主

2472发表于 2019-10-12 10:42:54
只看该作者楼主

内容接口类快服务接入指南(二) [复制链接]

本帖最后由 本无所为之2019-10-12 10:44:00 编辑


指南(一)说了概述以及服务接入流程,本文接着讲述内容接口类快服务接入的接口规范要求、账号绑定以及服务接入流程……


1、概述 和  2、服务接入流程  ,详情可见内容接口类快服务接入指南(一)

3. 接口规范要求

3.1 性能要求

  • 接口TPS(每秒请求次数)要求大于2000。

  • 接口时延要求,在最大TPS情况下,99%的请求时延小于150毫秒。

  • 接口稳定性要求,调用成功率> 99.99%。全年服务中断不超过20分钟。

  • 可靠性要求,系统需要支持水平扩容,满足业务发展。

3.2 安全要求

  • 接口协议:HTTPS。

  • HTTPS证书要求:使用合法CA颁发的证书,不允许使用自签名证书。

  • 请求方法:POST方式。

  • 接口响应大小限制,接口响应总大小不超过24KB,各字段大小限制参考接口文档定义。

  • 接口中的资源链接(如图片链接、音频链接等)要求是HTTPS协议。

3.3 认证要求

  • 接口需要有认证机制,提供标准OAuth2.0 或者AK/SK的身份认证方式。

3.3.1 AK/SK认证方式


参数列表类型M/O字段描述
accessKeyString(64)M开发者在华为快服务开放平台上配置的接入码(accessKey)
signString(256)M参数签名=Base64(HMAC-SHA256(secretKey, ts)),其中secretKey 为开发者在华为快服务开放平台上配置的接入密钥(secretKey)。
tsString(16)M

时间戳,用于加密和缓存穿透。

格式为:当前计算机时间和GMT时间(格林威治时间)1970年1月1号0时0分0秒所差的毫秒数。

例如:2018/1/1 08:00:00.000 的时间戳为”1514764800000”。


(1)防重放

出于防重放攻击的需要,服务端应该校验报文中的ts和当前实际时间相差在一个范围内。

例如:校验服务器侧时间戳与请求报文中的时间戳差值的绝对值(ABS),小于15分钟。


(2)签名算法

Sign的计算代码示例,服务器侧可以基于ts计算该sign,与请求中的sign比对是否相等,以达到验证客户端身份的目的。

Mac mac = Mac.getInstance(HMAC_SHA256);SecretKey secretKey = new SecretKeySpec(secret.getBytes(SystemCharsets.UTF_8), HMAC_SHA256);mac.init(secretKey);byte[] byteHMAC = mac.doFinal(ts.getBytes(SystemCharsets.UTF_8));byte[] sign = Base64.encodeBase64(byteHMAC);


3.3.2 OAuth2.0认证方式

遵循OAuth2.0标准。

接口错误码定义要求:


HTTP Error Code说明
400 Bad Request请求无效,由于请求格式错误服务器无法理解的请求。
401 Unauthorized请求需要用户身份验证
403 Forbidden服务器理解请求但不允许访问
404 Not found 服务器未找到与请求URI匹配的任何内容
429 UsageLimits限流,因为客户端请求数超过配额而进行限流,客户端可以选择延迟重试。
500 Server Internal Error内部服务器错误,服务器故障,服务不可用。


如果响应包含以上错误,在响应返回的errorCode和errorMessage字段里描述详细错误。

业务结果码(errorCode)和结果描述参考:


HTTP状态码errorCodeerrorMessage备注是否重试
2001Invalid parameter无效参数
4002Incorrect signature签名错误
4003Too many parameters参数过多
4004Unsupported signature method不支持此签名方式
4005Invalid/Used timestamp parameter时间戳无效
4006Unsupported open api不支持此接口
40120Invalid user id用户ID无效
40141Invalid API key无效API Key否
40142Session key invalid or no longer valid会话密钥无效
40143Access token invalid or no longer validAccess token无效或已失效
40164Access token expiredAccess token已过期
40360No permission to access user data无权访问用户数据
40361No permission to access data for this referer无权访问数据
500101Unknown error未知错误
500102Server internal error服务器错误
500103Service temporarily unavailable服务暂不可用
500104Unknown error未知错误
500105Service temporarily unavailable服务暂不可用
20010001The user’s domain state is null!领域状态为空
20010002The NLP result is null!NLP结果为空
20010003The domain code is wrong, can’t handle it!领域编码错误
20010004Add NLP result exception in Decision Summary!添加NLP结果异常到汇总决策
20010005No domain identified领域未识别
20010006No asrText or malformated没有asrText或者格式错误
20010103DeviceId is nullDeviceId为空
20010105Request data format error请求数据格式错误
20010106Request body oversize请求数据body超限
20010107Request data redundant field exists请求数据存在多余字段
20010108Request param is null请求字段为空
20010109Request deviceId is different请求数据Header和请求数据body的deviceId字段不同


4. 账号绑定

4.1 概述

内容接口类服务接入场景的账号绑定,主要用于华为用户访问开发者上的授权资源,如访问用户购买的付费节目,可选地支持开发者推送事件通知给华为用户

4.2 绑定方法

将华为账号绑定开发者的用户账号,用于华为用户访问开发者服务器上的授权资源,如访问用户购买的付费节目。

4.2.1 约束

开发者用户账号的开放必须基于OAuth2.0协议标准,华为快服务智慧平台当前仅支持采用授权码模式访问开发者的用户账号。

4.2.2 开发前准备

开发者已经存在支持OAuth2.0协议标准的账号服务器。

开发者已经存在H5授权页面。

4.2.3 账号绑定开发流程

内容接口类服务接入账号绑定流程如下:


(1)开发者在华为快服务智慧平台上定义快服务支持账号授权能力。

(2)用户请求账号授权,华为设备拉起开发者的账号授权H5页面


账号请求报文举例如下:

GET / authorize ? response_type = code & client_id = s6BhdRkqt3 & state = VU3f717ItF2Gu0Q2o2h9vIUfie8EqZDH &    redirect_uri = https % 3 a % 2 f % 2 fhag.cloud.huawei.com % 2 faccount - link % 2 fv1 % 2 fabilities % 2 fe2aa80c7b934484697c18b3c0d51af38 HTTP / 1.1Content - Type: application / x - www - form - urlencoded


(3)用户在H5授权页面输入在开发者服务器上注册的账号和密码,提交到开发者服务器,服务器校验账号和密码有效性后分配授权码Code,并根据华为设备请求携带的redirect_uri设置重定向地址


账号授权正常响应报文举例如下:

HTTP / 1.1 302 FoundLocation: https: //hag.cloud.huawei.com/account-link/v1/abilities/    e2aa80c7b934484697c18b3c0d51af38 ? code = SplxlOBeZQQYbYS6WxSbIA & state = VU3f717ItF2Gu0Q2o2h9vIUfie8EqZDH


(4)华为快服务智慧平台根据授权码Code,向开发者服务器申请用户的AT(AccessToken)/RT(RefreshToken)


AT请求报文举例如下:

POST / token HTTP / 1.1Content - Type: application / x - www - form - urlencodedgrant_type = authorization_code & code = SplxlOBeZQQYbYS6WxSbIA &    redirect_uri = https % 3 a % 2 f % 2 fhag.cloud.huawei.com % 2 faccount - link % 2 fv1 % 2 fabilities % 2 fe2aa80c7b934484697c18b3c0d51af38


AT请求响应报文举例如下:

HTTP / 1.1 200 OKContent - Type: application / json;charset = UTF - 8Cache - Control: no - storePragma: no - cache {    'access_token': '2YotnFZFEjr1zCsicMWpAA',    'token_type': 'bearer',    'expires_in': 3600,    'refresh_token': 'tGzv3JOkF0XG5Qx2TlKWIA'}


(5)华为快服务智慧平台保存华为账号UID和开发者服务器分配的AT/RT的关联关系,并返回给华为设备侧,账号授权成功。


(6)用户在华为设备侧执行服务查询,华为快服务智慧平台获取用户的AT,传递给开发者服务器,开发者服务器根据AT即可校验用户的合法性。


4.2.4 双向账号绑定流程(可选流程)


用户完成帐号绑定后,如果开发者服务器需要对华为用户推送事件消息,则需要实现双向账号绑定流程。


说明:

开发者服务器侧推送的事件,需要华为端侧适配开发才能读取,否则开发者服务器侧推送的事件,华为端侧用户无法感知。



1、华为端侧通过开发者的appID调用接口获取用户的授权码Code。参考:卡片类快服务开发指南-章节12. 快应用卡片API说明【INF10】。


2、华为端侧通过华为快服务智慧平台发起双向账号绑定流程,传递参数:华为端侧获取的华为账号信息,授权码Code。


3、华为快服务智慧平台向开发者服务器下发双向账号绑定指令。


指令请求报文样例如下所示:

{    'header': {        'type': 'Directive',        'timestamp': '15869741258',        'name': 'AcceptGrant',        'namespace': 'Authorization'    },    'inquire': {        'inquireId': 'efd1f6ca-8fdf-11e8-9eb6-529269fb1459',        'payload': {            'grant': {                'type': 'OAuth2.AuthorizationCode',                'code': 'ZU5uc3v045B6gkNSIXmf0414BQJQ5O37'            },            'grantee': {                'type': 'Bearer',                'accessToken': '7Weer0UbuB67eK5f837K0C81jA721a7ZdYfgWuQF5f3xU8Yiphn7ji72l1ZY9YtC'            }        }    }}


指令响应报文样例如下所示:

{    'version': '1.0',    'reply': {},    'errorCode': '0',    'errorMessage': 'ok'}


4、开发者服务器调用华为鉴权服务器的接口,根据授权码Code获取用户openID和AcessToken。参考:卡片类快服务开发指南-章节12. 快应用卡片API说明【INF2】、【INF4】。


5、开发者服务器完成帐号和华为用户的openID/AT/RT的绑定关系。


6、开发者服务器完成帐号绑定后,调用华为快服务智慧平台接口将帐号绑定结果发送给华为快服务智慧平台。参考:卡片类快服务开发指南-章节12. 快应用卡片API说明【INF5】、【INF6】。


4.2.5 AT刷新流程


1、华为快服务智慧平台查询用户的AT时,如果AT已经过期,则会使用RT向开发者服务器重新申请AT。


AT刷新请求报文样例如下:

POST / token HTTP / 1.1Content - Type: application / x - www - form - urlencodedgrant_type = refresh_token & refresh_token = tGzv3JOkF0XG5Qx2TlKWIA


说明:

开发者需要保证刷新AT和请求AT的URL保持一致

AT刷新请求响应报文样例如下:

HTTP / 1.1 200 OKContent - Type: application / json;charset = UTF - 8Cache - Control: no - storePragma: no - cache {    'access_token': '2YotnFZFEjr1zCsicMWpAA',    'token_type': 'bearer',    'expires_in': 3600,    'refresh_token': 'tGzv3JOkF0XG5Qx2TlKWIA'}


2、开发者服务器调用华为快服务智慧平台的接口,重新同步用户的AT/RT,参考:卡片类快服务开发指南-章节12. 快应用卡片API说明【INF6】和【INF8】

5. 服务运行流程

举报
楼主发表于 2019-10-12 10:45:32
只看该作者沙发

顶顶,希望对大家有帮助

举报
楼主发表于 2019-10-12 15:15:43
只看该作者板凳

顶顶顶顶

举报

您需要登录后才可以回帖

登录注册
发表回复