关联阅读：（点击标题即可跳转）

卡片类快服务开发指南（一）

卡片类快服务开发指南（二）

指南（一）（二）叙述了：1、卡片介绍 2、结构说明 3、第一个卡片 4、附录 5、卡片类快服务设计规范 6、系统推荐类快应用卡片快服务开发指南 7、用户查询类快应用卡片快服务开发指南 8、酒店垂域快应用卡片内容数据接入接口规范，本文继续往下介绍……

9. 资讯文摘垂域快应用卡片内容数据接入接口规范

为了规范华为快服务智慧平台面向开发者的内容数据接入开发指南，包括业务流程、接口定义。确保业务理解一致，开放接口定义统一，便于开发者更好的使用。

术语、定义和缩略语：

术语	英文	中文
HAG	Huawei Ability Gallery	华为快服务智慧平台
HTTP	Hyper Text Transfer Protocol	超文本传输协议
XML	Extensible Markup Language	可扩展标记语言
JSON	JavaScript Object Notation	是一种轻量级的数据交换格式

9.1 典型业务场景

9.1.1 开发者内容入库场景

华为通过服务聚合网关定时调用开发者接口获取开发者内容数据入库，同时提供接口供开发者调用，满足开发者需要实时同步内容数据的场景，流程如下图所示：

9.2 开发者内容接入CheckList

9.2.1 开发者内容接入

在开发者内容数据引入前通过Checklist检查数据引入的总数据量级、日变化量级等信息。

检查项	描述信息	结果
数据总量	开发者能够提供给华为的总数据量（条）
日变化量	开发者能够提供给华为数据的日变化量（条）
数据大小	单条数据的最大大小
同步频度	全量同步、增量同步的频度。

9.3 服务器侧接口规范

9.3.1 接口协议

接口协议：HTTPS。
数据格式：请求和响应原则上要求采用Json和urlEncode的报文格式。
请求方法：支持POST（提交类）方式。

9.3.2 URL定义

华为快服务智慧平台服务器提供的接口URL定义如：http[s]://{域名}/{模块}?{参数}，URL中各部分的说明如下：

字段	含义	样例
域名	对外提供接口的地址	hag.cloud.huawei.com
模块	服务名称	hag-gw

接口资源和参数名称统一采用驼峰命名法。例如：cardList。

9.4 服务器侧接口定义

9.4.1 资讯文摘类内容数据接口

9.4.1.1 应用级AccessToken获取接口

1、接口描述

开发者服务器访问华为服务器时，Server之间认证的应用级Token。

2、接口地址

项目	描述
消息方向	“开发者服务器” > “华为鉴权服务器”
方法	HTTPS+POST
URI（测试环境）	https://logintestlf.hwcloudtest.cn/oauth2/v2/token
URI（生产环境）	https://login.cloud.huawei.com/oauth2/v2/token

3、请求消息

（1）Request Header：

key	value	备注
Content-Type	application/x-www-form-urlencoded

（2）Request Body：

key	type	value	备注
grant_type	string	client_credentials	固定值
client_id	string	第三方开发者的appID
client_secret	string	第三方开发者的appSecret

最终的Body体是一个字符串，根据上面的字段和字段值拼接而成：“key1=” + urlEncode(value1) + ”&key2=“ + urlEncode(value2) + …

每个字段的值都要做urlEncode。

4、响应消息

（1）若请求无误，服务器将返回一段JSON文本，包含以下参数：

字段名	类型	是否必填	备注
access_token	string	必填	AT
expire_in	int	必填	AT的有效期，以秒为单位。默认1小时。
scope	string	非必填	AT最终的访问范围

（2）若请求错误，服务器将返回一段JSON文本，包含以下参数：

字段名	类型	是否必填	备注
error	string	必填	错误码
error_description	string	必填	错误描述信息

9.4.1.2 推送资讯文摘信息内容数据

1、接口描述

本接口用于三方开发者实时向华为快服务智慧平台推送资讯文摘类内容信息。包括但不限于新闻资讯、健康资讯、汽车资讯、财经资讯、驾考资讯、学习资讯等。

2、接口地址

项目	描述
调用关系	三方开发者服务器-> 华为服务器
调用方式	https+post
请求地址	https://hag.cloud.huawei.com/hag-gw/v1/informations
约束	1. 为了节省带宽第三方开发者的http请求消息要开启gzip压缩。 2. 一次请求最多接收200条数据，超过200条则返回失败。

3、请求报文

（1）Request Header：

参数列表	类型	M/O	字段描述
x-appid	String	M	第三方开发者的appID
Authorization	String	M	应用级AccessToken
Content-Type	String	M	固定值，填application/json。
Accept	String	M	固定值，填application/json。

（2）Request Body：

参数列表	类型	M/O	字段描述
requestTime	String	M	请求报文的发送时间，格式：yyyyMMddHHmmssSSS(UTC)。
requestId	String	M	事件唯一ID。在消息是否重传、以及撤销时作唯一识别标识。如果重传，则需要保证重传消息的requestId与原消息的requestId一致，服务端会对重复请求进行过滤处理。其他情况，则需要保证每次requestId不同。可以使用UUID作为requestId； Pattern：[a-zA-Z0-9-] 最大长度64字节。
countryCode	String	M	国家码，如CN，最大长度8字节。
language	String	M	语言类型，如ZH，最大长度8字节。
abilityId	String	M	当一个开发者有多个Ability时，支持按照不同的Ability推送内容数据。AbilityID为联盟上架Ability时分配的ID信息，最大长度32字节。
data	JsonObject	M	批量推送的资讯文摘数据

（3）data结构体的定义如下所示：

参数列表	类型	M/O	字段描述
contents	JsonArray	M	资讯文摘内容信息列表

（4）contents的结构体：

参数名	参数类型	M/O	参数描述	参数作用
contentId	String	M	资讯文摘内容信息唯一标识，各开发者保证本开发者内唯一。最大长度32字节。	用于数据修改、删除时的唯一匹配索引。
pubTime	String	M	发布时间，格式’YYYY-MM-DD HH:MM:SS’。	用于排序参考。
title	String	M	资讯文摘标题，最大长度128字节。	检索条件
subtitle	String	O	资讯文摘附标题，最大长度128字节。	检索条件
digest	String	M	资讯文摘的摘要信息，最大长度512字节。	检索条件
source	String	M	资讯文摘来源，最大长度64字节。	检索条件
imgUrl	String	O	资讯文摘配图的URL，多图时通过逗号分隔URL；最大长度512字。	暂不使用
detailUrl	String	O	点击本条资讯文摘的详情页URL，最大长度512字。	暂不使用
text	String	M	新闻正文，最大长度1024字节。	检索条件
category	String	M	资讯文摘类别新闻资讯、财经资讯、旅游资讯、健康资讯、汽车资讯。	检索条件
tag	String	M	资讯文摘标签，资讯文摘内容标签，例如姚明，篮协，主教练等，可以多个并以逗号分隔。	检索条件
city	String	O	城市，用于识别本地新闻，例如北京、深圳。	检索条件
region	ImageInfo	O	区县，用于识别本地信息，例如海淀、朝阳。	检索条件
type	String	O	资讯文摘类型，纯文本、图文、视频、音频、图集、GIF。	检索条件
clkNum	Integer	O	点击次数	排序参考
upTimes	Integer	O	顶次数	排序参考
downTimes	Integer	O	踩次数	排序参考
replyCount	Integer	O	跟帖数	排序参考
heat	Integer	O	信息内容热度等级	排序参考
请求消息格式： { “requestTime”: “69d53781-3527-4918-9780-2bf6626fe4af”, “requestId”: “ow1oDF6bBgW3CSIh”, “countryCode”: “CN”, “language”: “ZH”, “abilityId”: “106”, “data”: { “contents”: [ { “contentId”: “10000001000”, “pubTime”: “2017-04-17 11:35:27”, “title”: “北方多地迎沙尘天北京市区能见度降低”, “subtitle”: “北方多地迎沙尘天北京市区能见度降低”, “digest”: “北方多地迎沙尘天北京市区能见度降低”, “source”: “澎湃新闻”, “imgUrl”: “http://s.cimg.163.com/i/cms-bucket.nosdn.127.net/6cbb4f1eb6644765b8b28c5f3288a81220170417113500.jpeg.1080x548.auto.jpg“, “detailUrl”: “http://c.m.163.com/nc/qa/3g-expand/huawei-photo.html?setid=2250334&channelid=0001“, “text”: “北方多地迎沙尘天北京市区能见度降低,对面相逢不相识”, “category “: “新闻资讯”, “tag”: “”, “city”: “北京”, “region”: “”, “type”: “图片”, “clkNum”: “0”, “upTimes”: “0”, “downTimes”: “0”, “replyCount”: “0”, ”countryCode”: “CN”, “language”: “zh”, } ] } }

4、响应报文

状态码	响应说明
200	资讯文摘内容同步成功，无响应消息体。
400	参数校验失败，code 为：invalidParam 响应消息体样例： { “code”: “invalidParam”, “desc”: “Paramter {} is invalid/should not be null/should be in [x,y]. “ }
401	网关验证应用级AT过期或AT无效，需要重新申请AT。 { “error”: “session timeout” }
403	网关验证处理开发者权限失败，没有权限调用华为快服务智慧平台的服务。 { “error”: “access forbidden” }
404	开发者请求的url路径不存在。响应消息体样例： { “error”: “invalid path” }
406	开发者请求不符合网关的规范，比如缺少必备Header等。响应消息体样例： { “error”: “invalid AcceptType”, “moreInfo”: “should be application/json” }
429	限流，因为客户端请求数超过配额而进行限流，code为： usageLimits。客户端可以以指数退避方式延时重试，重试周期最小30s起。响应消息体样例： { “code”: “usageLimits”, “desc”: “Request per minutes exceeds max limit.” }
500	服务器内部错误， code为：backendError。客户端可以以指数退避方式延时重试，重试周期最小1s起。响应消息体样例： { “code”: “backendError”, “desc”: “Backend server error.” }
其他错误	对于4xx响应，客户端应该根据error信息，定位解决问题。对于5xx响应，客户端可以以指数退避方式延时重试，重试周期最小1s起。

10. 财经垂域快应用卡片内容数据接入接口规范

术语、定义和缩略语：

术语	英文	中文
HAG	Huawei Ability Gallery	华为快服务智慧平台
HTTP	Hyper Text Transfer Protocol	超文本传输协议
XML	Extensible Markup Language	可扩展标记语言
JSON	JavaScript Object Notation	是一种轻量级的数据交换格式

10.1 典型业务场景

10.1.1 开发者内容入库场景

10.2 开发者内容接入CheckList

10.2.1 开发者内容接入

在开发者内容数据引入前通过Checklist检查数据引入的总数据量级、日变化量级等信息。

检查项	描述信息	结果
数据总量	开发者能够提供给华为的总数据量（条）
日变化量	开发者能够提供给华为数据的日变化量（条）
数据大小	单条数据的最大大小
同步频度	全量同步、增量同步的频度。

10.3 服务器侧接口规范

10.3.1 接口协议

接口协议：HTTPS。
数据格式：请求和响应原则上要求采用Json的报文格式。
请求方法：支持POST（提交类）方式。

10.3.2 URL定义

华为快服务智慧平台服务器提供的接口URL定义如：http[s]://{域名}/{模块}?{参数}，URL中各部分的说明如下：

字段	含义	样例
域名	对外提供接口的地址	hag.cloud.huawei.com
模块	服务名称	HAGGWService

接口资源和参数名称统一采用驼峰命名法。例如：cardList。

10.3.3 与开发者的状态码/错误码定义

与客户端返回的状态包包括HTTP状态码和业务错误码。

10.3.3.1 HTTP状态码

HTTP的状态码要求使用HTTP协议中的已有定义，参考RFC 2616的规范定义；禁止重复定义HTTP协议中已有的相应代码。

10.3.3.2 业务错误码

当请求错误或执行失败时，需要在Content-body中明确定义相关的错误码。业务错误码的定义和说明如下：

参数名	参数类型	可选	说明
code	String	必选	错误码，请求成功时为0。
desc	String	可选	错误原因，请求成功时可以为空。

1、错误码定义：

业务错误码	错误信息	备注
0	OK	成功
1	Invalid parameter	无效参数
2	Incorrect signature	签名错误
3	Too many parameters	参数过多
4	Unsupported signature method	不支持此签名方式
5	Invalid/Used timestamp parameter	时间戳无效
6	Unsupported open api	不支持此接口
12	Session key invalid or no longer valid	会话密钥无效
31	Forbidden	信息校验失败
32	Data parse error	数据解析出错
80	Request Timeout	请求超时
101	Unknown error	未知错误
102	Server internal error	服务器错误
103	Service temporarily unavailable	服务暂不可用

2、说明：

（1）业务错误

返回错误码非0，则认为是业务处理出错，需要服务器检查错误码，定位错误原因，例如：auth失败，参数不对，超出容量等。需要先解决参数问题，再向服务器端重新发起请求。<

（2）http错误

返回的状态码非200，表示服务端内部发生错误，客户端需要重试。

10.4 服务器侧接口定义

10.4.1 财经类内容数据接口

10.4.1.1 获取财经类内容数据（financialInfoList）

1、接口描述

本接口用于华为服务聚合网关从第三方服务器获取财经内容信息。

2、接口地址

项目	描述
调用关系	“华为服务器” > “第三方服务器”
调用方式	HTTPS+POST
请求地址	开发者在Ability开发平台配置的数据开放地址。
约束	1. 为了节省带宽第三方开发者的响应消息要开启gzip压缩； 2. 为了避免服务器调用的连接的开销，第三方开发者要支持http：keep-alive，华为服务器使用http长连接的方式进行服务的调用。

3、请求报文

参数列表	类型	M/O	字段描述
appKey	String	M	开发者在华为Ability开发平台上配置的访问accessKey。
appSecret	String(256)	M	参数签名=base64(hmac-sha256(secretKey, ts))secretKey为华为分配给开发者服务器的访问秘钥。
countryCode	String	O	国家码，不带是默认按照CN处理。
language	String	O	语言类型，不带时默认按照ZH处理。
abilityId	String	O	当一个开发者有多个Ability时，支持按照不同的Ability获取内容数据。
ts	String	M	时间戳，用于加密和缓存穿透。格式为：当前计算机时间和GMT时间(格林威治时间)1970年1月1号0时0分0秒所差的毫秒数。
pageSize	Integer	M	每页返回记录的数量，默认200条。如=200 则第三方开发者将200条财经内容数据返回给华为，实际返回的可以少于200条。
page	Integer	M	返回记录的开始页数，首次请求带“0” 。
请求报文 { “appKey”: “ow1oDF6bBgW3CSIh”, “appSecret”: “”, “countryCode”: “CN”, “language”: “ZH”, “abilityId”: “106”, “ts”: “1460032806000”, “pageSize”: “200”, “page”: “1” }

4、响应报文

参数列表	类型	M/O	字段描述
code	String	M	业务错误码
desc	String	O	错误结果描述，可以是成功信息ok或失败原因。
totalPage	Integer	M	满足数据的总页数
currentPage	Integer	M	当前页数
data	JsonObject	O	批量获取的数据
响应报文格式 { “code”: “0”, “desc”: “OK”, “totalPage”: “5”, “currentPage”: “1”, “data”: { “ contents “: [ { “ contentId “: “1001”, “ type “: “0”, “code”: “600311”, “name”: “荣华实业”, “description”: “”, “exchange”: “上海证券交易所”, “mbmChartImageUrl”: “http://quote.eastmoney.com/sh600311.jpg“, “mbmChartUrl”: “http://quote.eastmoney.com/chart/h5.html?id=6003111&type=r“, “url”: “http://quote.eastmoney.com/sh600311.html'  }, { “ contentId “: “1002”, “ type “: “0”, “code”: “000565”, “name”: “渝三峡”, “description”: “”, “exchange”: “上海证券交易所”, “mbmChartImageUrl”: “http://quote.eastmoney.com/sz000565.jpg“, “mbmChartUrl”: “http://quote.eastmoney.com/chart/h5.html?id=0005652&type=r“, “url”: “http://quote.eastmoney.com/sz000565.html“ } ] } }

（1）财经内容数据data结构体的定义如下所示：

参数列表	类型	M/O	字段描述
contents	JsonArray	O	财经内容信息列表

（2）contents的结构体：

参数名	参数类型	M/O	参数描述	参数作用
contentId	String	M	财经内容信息唯一标识，各开发者保证本开发者内唯一。最大长度32字节。	用于数据修改、删除时的唯一匹配索引。
type	String	M	类型，股票；基金；债券；期货；外汇；理财等。最大长度32字节。	检索条件
code	String	M	财经内容代码。例如，type为0：股票则为股票编码。最大长度16字节。	检索条件、结果展示。
name	String	M	财经内容名称。例如，type为0：股票则为股票名称。最大长度64字节。	检索条件、结果展示。
description	String	O	描述信息，不超过512字节。	检索条件
exchange	String	O	上市交易所。最大长度64字节。	检索条件、结果展示。
mbmChartImageUrl	String	O	行情页图片URL，用于获取行情图在卡片中展示。最大长度512字节。	结果展示
mbmChartUrl	String	O	行情页URL，用于在卡片上点击行情图后跳转行情页。最大长度512字节。	结果展示后的跳转引流
url	String	O	详情页URL，用于跳转详情页。最大长度512字节。	结果展示后的跳转引流

11. 快应用卡片类快服务开发工具安装指南

11.1 卡片Demo体验

下载示例代码并运行示例代码体验开发流程。

11.1.1 卡片开发参考Demo下载

点击下载CardDemo.rar。

11.1.2 卡片开发参考Demo介绍

卡片demo提供了一系列快应用卡片的样例代码，本身是一个标准的快应用程序，可以使用华为快应用IDE打开。

下载demo工程，解压到本地路径，打开IDE，在菜单选择“文件” > “打开项目”，选择解压后的工程文件夹路径，点击“选择文件夹”打开工程。

所有的卡片都按照规范在manifest.json中的widgets属性字段中声明，所有的代码都仅做参考，并没有固定的实现方式。

11.2 快应用IDE开发工具安装

开发工具安装，参考：安装快应用IDE。

卡片类快服务开发指南（三）

9. 资讯文摘垂域快应用卡片内容数据接入接口规范

9.1 典型业务场景

9.1.1 开发者内容入库场景

9.2 开发者内容接入CheckList

9.2.1 开发者内容接入

9.3 服务器侧接口规范

9.3.1 接口协议

9.3.2 URL定义

9.4 服务器侧接口定义

9.4.1 资讯文摘类内容数据接口

9.4.1.1 应用级AccessToken获取接口

9.4.1.2 推送资讯文摘信息内容数据

10. 财经垂域快应用卡片内容数据接入接口规范

10.1 典型业务场景

10.1.1 开发者内容入库场景

10.2 开发者内容接入CheckList

10.2.1 开发者内容接入

10.3 服务器侧接口规范

10.3.1 接口协议

10.3.2 URL定义

10.3.3 与开发者的状态码/错误码定义

10.3.3.1 HTTP状态码

10.3.3.2 业务错误码

10.4 服务器侧接口定义

10.4.1 财经类内容数据接口

10.4.1.1 获取财经类内容数据（financialInfoList）

11. 快应用卡片类快服务开发工具安装指南

11.1 卡片Demo体验

11.1.1 卡片开发参考Demo下载

11.1.2 卡片开发参考Demo介绍

11.2 快应用IDE开发工具安装