WebApi编写说明

一. 简介

web API 别名webhook，是一个方法为POST、请求响应body格式为json的HTTP/HTTPS接口，基于restful风格，不限语言。供开发者在DUI平台使用内容资源，其中json的格式为key、value对。

二. API配置

属性	说明
URL	开发者在定制平台上输入的资源地址，强烈建议使用https。
参数名称	请求json的key，一般需要和对话的slot对应
取值	请求json的value。可以对应于对话的某个slot，对话调用webhook时，会将解析出的slot值作为对应key的value值传递给webhook。也可以填入一个常量值，该情况下，当webhook被调用时，对应key的值为常量

返回结果

返回的json可以通过约定的格式适配内置控件，内置控件包括：内容卡片控件、列表控件、多媒体控件、内嵌网页控件，具体描述见：https://www.duiopen.com/docs/ct_skill_nativeAPI中的"nativeapi返回数据规范"。

三. webhook示例

以汇率换算webhook为例，配置webhook服务接口地址：

技能内容部 > webhook接口编写说明 > worddav1ec0e891ce5070b874c6c75fa945aa85.png

请求参数设置：

技能内容部 > webhook接口编写说明 > worddav8b3aa74dda03bb3acb1429b12c507908.png

返回数据字段映射

如果使用dui标准控件，则返回字段名则需要和控件字段一致，标准控件的使用参数参考：http://www.duiopen.com/docs/ct_skill_nativeAPI。如果是开发者自定义控件或者自定义使用规则，则不受此限制。

如果是使用返回字段进行nlg播报，则使用字符$来引用返回字段。

比如定义对话回复：

技能内容部 > webhook接口编写说明 > worddav47bda3a3025e058ce6a329eba74bc668.png

数据示例：

在dui控制台输入："100欧元兑换多少人民币"说法

技能内容部 > webhook接口编写说明 > worddav05f737d2f3038391b47bd99732e6ce36.png
dui将会对说法进行解析，然后映射成定义的参数字段，对webhook服务发起请求。本次示例请求uri如下：

/webhook-v2/exchange/index?productId=tryProductId&deviceName=DUI-ODCP-f7482e70-2547-11ea-9135-9d3d851244a8&userId=DUI-ODCP-f7482e70-2547-11ea-9135-9d3d851244a8_tryProductId&RecordId=cf776e0f51314f6498a65f149019e7d5&SessionId=152645f44b354f758e67d7710893e0b8&skillId=2019031800001146

uri参数说明

参数	类型	说明
productId	string	所属产品ID
deviceName	string	设备ID
userId	string	用户ID
RecordId	string	本次请求全链路唯一ID
SessionId	string	本次会话ID
skillId	string	技能ID

汇率webhook收到的POST请求body数据如下：

{
	"nlu": {
		"skillId": "2019031800001146",
		"input": "100欧元兑换多少人民币",
		"skill": "汇率",
		"skillVersion": "latest",
		"source": "dui",
		"systime": 72.419189453125,
		"semantics": {
			"request": {
				"slots": [
					{
						"name": "intent",
						"value": "汇率"
					},
					{
						"pos": [
							0,
							2
						],
						"rawvalue": "100",
						"name": "原始金额",
						"rawpinyin": "100",
						"value": "100"
					},
					{
						"pos": [
							3,
							4
						],
						"rawvalue": "欧元",
						"name": "原始币种",
						"rawpinyin": "ou yuan",
						"value": "欧元"
					},
					{
						"pos": [
							9,
							11
						],
						"rawvalue": "人民币",
						"name": "目标币种",
						"rawpinyin": "ren min bi",
						"value": "人民币"
					}
				],
				"task": "汇率"
			}
		},
		"version": "2019.1.15.20:40:58",
		"timestamp": 1577080233
	},
	"duiWidget": "text",
	"from": "欧元",
	"fromNumber": "100",
	"intent": "汇率",
	"rec": "100欧元兑换多少人民币",
	"to": "人民币"
}

请求body字段说明：

参数	类型	说明
nlu	Object	nlu语义解析相关数据
from	string	定义的参数：原始币种
to	string	定义的参数：目标币种
fromNumber	string	定义的参数：换算金额

webhook返回的数据：

{
	"errorcode": "100100",
	"extra": {
		"from": "欧元",
		"to": "人民币",
		"fromNumber": "100",
		"result": "776.56"
	}
}

根据控件约定的字段映射，或者直接引用返回的数据，就可以进行数据展示。
完整的一次webhook请求，数据交换已经完成了。

四. 示例代码

语言	更新说明	源码下载
go	1.汇率查询示例源码V1.0	下载
java	1.汇率查询示例源码V1.0	下载