【荣耀开发者服务平台—百亿曝光扶持等你来】智慧服务内容接口卡片接入指南

荣耀开发者服务平台(HONOR Developers)是荣耀面向开发者的统一生态入口，通过聚合周边内外部系统，分全球多站点部署，为全球开发者提供业务全生命周期的商业支撑服务。

平台可为软硬件合作伙伴带来三大应用场景服务，包括主动服务的场景化体验智慧服务，智能协同的跨设备互联的智慧生态以及应用与游戏出海服务。同时，荣耀帐号服务、推送服务、运动健康等开放能力和业务也提供了多样化的合作选择。

当前荣耀智慧服务百亿级曝光扶持计划正火热进行中~

一、接入指南

荣耀智慧服务为开发者提供一站式接入服务能力，和全场景、多终端、多入口的AI分发能力，为开发者提高业务推广效率，同时给用户提供便捷、贴心、智能的服务体验。目前包含四种接入类型：快捷服务、快应用卡片、安卓应用卡片、内容接口卡片，呈现显示包括卡片和图标等，本文将提供内容接口卡片接入指南。

 

二、接口开发指南

1. 性能要求

（1）接口TPS（每秒请求次数）要求：要求三方接口的TPS>2000。

（2）接口时延要求：在最大TPS情况下，99%的请求时延小于150毫秒。

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

（4）可靠性要求：系统需要支持水平扩容，满足业务发展。

2. 安全要求

2.1 接口协议

接口协议：HTTPS。

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

数据格式：请求和响应采用Json的报文格式。

请求方法：POST方式。

报文压缩：响应消息应开启gz压缩，减少带宽开销。

长连接：为避免反复TLS建连的开销，支持http：keep-alive，荣耀服务器使用长连接的方式进行调用。

2.2 接口认证方式

• AK/SK的身份认证方式
• Header认证
• OAuth Client模式认证

2.2.1 AK/SK认证

成员名称	描述	必填	类型	取值范围
accessKey	开发者在荣耀服务开放平台上配置的接入密钥（accessKey）	是	String	/
secretKey	开发者在荣耀服务开放平台上配置的接入码（secretKey）	否	String	/
sign	参数签名=Base64（HMAC-SHA256（secretKey， ts））。 其中secretKey 为开发者在荣耀服务开放平台上配置的接入密钥（secretKey）。	是	String	/
ts	时间戳，用于加密和缓存穿透。 格式为：当前计算机时间和GMT时间（格林威治时间）1970年1月1号0时0分0秒所差的毫秒数。 例如：2018/1/1 08:00:00.000 的时间戳为"1514764800000"。	是	String	/

（1）防重放
出于防重放攻击的需要，服务端应该校验报文中的ts和当前实际时间相差在一个范围内。
例如：校验服务器侧时间戳与请求报文中的时间戳差值的绝对值（ABS），小于15分钟。

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

String secret = "密钥";

String ts = "从消息头中获取ts";

Mac mac = Mac.getInstance("HmacSHA256");

SecretKey secretKey = new SecretKeySpec(secret.getBytes(SystemCharsets.UTF_8), "HmacSHA256");

mac.init(secretKey);

byte[] byteHMAC = mac.doFinal(ts.getBytes(SystemCharsets.UTF_8));

String sign = new String(Base64.encodeBase64(byteHMAC), StandardCharsets.UTF_8);

例如：

secret 为 2e3b71f5def64d95a727314f028bf5aa， ts为1547630863716时，签名结果应该为： 6lFqepUu79KSxVCsrXyB/aLVFIdutsTLLx1cZjxDE4I=

2.2.2 Header认证

开发者在荣耀服务开放平台上配置对应的key及value值，支持多个。

2.2.1 OAuth Client模式认证

OAuth2.0协议规范，可访问OAuth 2.0官方网站 OAuth 2.0 — OAuth

当前仅支持Client模式

3. 接口响应大小限制

（1）接口响应总大小不超过1MB。

（2）其余字段的返回大小详见具体描述。

（3）接口中的资源链接（如图片链接、音频链接等）要求是HTTPS协议。

4. 隐私要求

提供隐私通知（notice），用于在用户使用服务时呈现。

其他的隐私要求，在双方合作协议中补充。

5. 响应错误描述

业务结果码（errorCode）和结果描述参考：

errorCode	errorMessage	备注
101101100001	Invalid parameter	无效请求参数
101101100002	Query fulfillment info failed	查询履行数据失败
101101100003	Invoke Cp failed	请求CP失败
101101100004	cp response error	CP响应失败
101101100005	Invalid configuration value	无效配置
101101100006	Build authentication of cp failed	构造CP鉴权信息失败
101101100007	Invoke cp timeout	访问CP超时
101101100008	get cache error	获取缓存失败
101101100009	Template response error	模板响应为空
101101100010	response convert failed	响应转化失败
101109110100	aes init failed	AES初始化失败
101101100010	get token redis lock failed	获取token锁失败
101101100011	get news redis lock failed	获取新浪锁失败
101101100008	Size of cp response exceed limit	cp 响应的大小超出限制
101101100012	Invalid cp url param	无效请求cp_url参数
101101100013	刷新token失败	刷新token失败
101101100014	get token info failed	获取token失败
101101100015	.	生成签名失败
101101100016	Get fuse resource failed	获取熔断的resource失败
101101100017	error url	错误的url
101101100018	The cp is degraded	cp被降级
101109110100	aes init failed	AES初始化失败

6. 公共请求参数/响应参数

6.1 服务履行接口

基本信息

方法：POST

说明：调用您在荣耀开发者联盟上录入的Fulfillment的URL地址，携带服务履行相关信息

请求头域

成员名称	描述	必填	类型	取值范围
accessKey	您在荣耀开发者联盟上录入的Fulfillment的接入码（accessKey）	是	String	/
secretKey	您在荣耀开发者联盟上录入的Fulfillment的接入密钥（secretKey）	是	String	/
sign	参数签名=Base64(HMAC-SHA256(secretKey, ts))。其中secretKey 为您在荣耀开发者联盟上录入的Fulfillment的接入密钥（secretKey）	是	String	/
ts	时间戳，用于加密和缓存穿透。格式为：当前计算机时间和GMT时间(格林威治时间)1970年1月1号0时0分0秒所差的毫秒数。	是	String	/

6.2 请求参数：FulfillmentReq

请求的body信息如下，slots为各垂类接口定义信息，具体内容参考各垂类接口定义

消息体样例

{
	"endpoint": {
		"device": {
			"base": {
				"deviceId": "string",
				"deviceType": "phone"
			},
			"presentation": {
				"screenOrientation": "horizontal",
				"net": "wifi",
				"location": {
					"longitude": "string",
					"latitude": "string",
					"locationSystem": "WGS84"
				}
			}
		},
		"locale": "zh-CN",
		"countryCode": "zh",
		"timeZone": "+0800",
		"localTime": "string"
	},
	"inquire": {
		"inquireId": "string",
		"intent": {
			"serviceId": "string",
			"intentName": "string",
			"status": "online",
			"slots": {}<!--具体槽位信息见不同垂类接口定义-->
		}
	}
} 

6.3 响应参数：FulfillmentResp

响应信息如下，templateContent为各垂类接口响应信息，具体内容参考各垂类接口定义

消息体样例

{
	"reply": {
		"commands": [{
			"head": {
				"namespace": "string",
				"name": "string"
			},
			"body": {
				"displayTemplate": "string",
				"templateType": "string",
				"templateInstance": "string",
				"templateContent": {}<!--具体响应见不同垂类接口定义-->
			}
		}]
	},
	"code": "0",
	"message": "ok",
	"errorCode": "string",
	"errorMessage": "string",
	"version": "string"
}

7. 公共结构

FulfillmentReq

成员名称	描述	必填	类型	取值范围
endpoint	端侧信息	是	Endpoint	/
inquire	意图信息	是	IntentReq	/

Endpoint

成员名称	描述	必填	类型	取值范围
device	端侧设备相关信息	是	DeviceInfo	/
locale	用户的语言环境	否	String	最大长度：20
countryCode	归属地国家/区域码	否	String	最大长度：2
timeZone	时区，符合ISO-8601规范的UTC偏移量规则，以下形式表示：±[hh][mm]，如中国是 +0800	否	String	最大长度：5
localTime	端侧当前本地时间, format yyyyMMddHHmmssSSS	否	String	最大长度：17

DeviceInfo

成员名称	描述	必填	类型	取值范围
base	设备基础信息	是	DeviceBaseInfo	/
presentation	设备当前表现形态	否	DevicePresentationInfo	/

DevicePresentationInfo

成员名称	描述	必填	类型	取值范围
screenOrientation	横竖屏：horizontal, vertical	否	String	/
net	网络：wifi, 2g, 3g, 4g, 5g	否	String	/
location	地理位置信息	否	Location	/

DeviceBaseInfo

成员名称	描述	必填	类型	取值范围
deviceId	设备ID	是	String	最大长度：64
deviceType	设备类型 phone：手机 pad：平板 tv：大屏	是	String	最大长度：32
deviceModel	设备型号	否	String	最大长度：64
appVersion	端侧应用版本号	否	String	最大长度：64
sysVersion	系统版本号	否	String	最大长度：64
brand	品牌	否	String	最大长度：64
manufacture	厂商	否	String	最大长度：64

Location

成员名称	描述	必填	类型	取值范围
longitude	经度	否	String	最大长度：50
latitude	纬度	否	String	最大长度：50
locationSystem	坐标系统 WGS84：GPS设备获取的坐标 GCJ02：国测局加密坐标 BD09LL：百度球面坐标	否	String	/

IntentReq

成员名称	描述	必填	类型	取值范围
intent	意图过滤信息	是	IntentFilter	/
inquireId	请求id	否	String	最大长度：64

IntentFilter

成员名称	描述	必填	类型	取值范围
serviceId	服务id，荣耀服务平台创建的对应id	是	String	最大长度：64
intentName	意图名称	否	String	最大长度：64
intentCategory	意图分类	否	String	最大长度：64
apiKey	类型key	否	String	最大长度：64
slots	槽位map信息，参见模板schema定义	是	Map<String, SlotsInfo>	/

SlotsInfo

成员名称	描述	必填	类型	取值范围
name	槽位名称	是	String	最大长度：512
values	槽位值列表	是	List<Real>	/

Real

成员名称	描述	必填	类型	取值范围
real	槽位值	是	String	最大长度：512

FulfillmentResp

成员名称	描述	必填	类型	取值范围
code	返回码，0成功，其他失败	是	String	最大长度：32
message	描述信息	是	String	最大长度：256
version	版本号	否	String	最大长度：16
reply	履行结果	否	Reply	/
errorCode	错误码	否	String	最大长度：32
errorMessage	错误信息	否	String	最大长度：256

Reply

成员名称	描述	必填	类型	取值范围
commands	结果命令列表	是	List<Command>	/

Command

成员名称	描述	必填	类型	取值范围
head	命令头	否	CommandHead	/
body	命令体	是	CommandBody	/

CommandHead

成员名称	描述	必填	类型	取值范围
namespace	命名空间	否	String	最大长度：128
name	名称	否	String	最大长度：128

CommandBody

成员名称	描述	必填	类型	取值范围
displayTemplate	通用模板响应	否	Object	/
templateType	模板类型；取自入参中IntentFilter的apiKey字段	否	String	最大长度：64
templateInstance	模板示例	否	String	最大长度：32
templateContent	模板内容	否	TemplateContent	/

TemplateContent

成员名称	描述	必填	类型	取值范围
/	各垂类接口返回内容，参见模板schema定义，	否	Object	/

了解更多详情，欢迎访问荣耀荣耀开发者服务平台官网：https://developer.hihonor.com/

7 月 20 日 - 10 月 20 日，参与荣耀开发者服务平台注册认证，更多好礼相送。

官方联系方式：

官方微信：HONOR_Developer

官方邮箱：Developers_BD@hihonor.com