Webhook 接入方式会将语义理解服务生成的数据传递到您的 Web 服务中并从中获取结果。该 Web 服务需要开发者自己搭建，并且需要遵从平台预先定义好的输入输出。

1. 认证文件校验

目前开放平台将对开发者填写的 Webhook 服务地址做真实性校验（检测服务地址的有效性和开发者对服务地址是否有权限）。
在配置 Webhook URL 前请先下载技能的认证文件，并将认证文件配置在服务器中供平台检测。
1587868271656-a354821b-385b-452a-9af0-812758710912.png

认证文件的配置方法为：

  • 如果您开发的是基于 Tomcat 等运行的普通 Web 项目，请将下载的认证文件放到要配置的服务地址所属服务器软件上。PS：服务器软件是指 Tomcat / Nginx / Jetty 等，而不是运行服务器所依赖的操作系统。文件存放路径为：服务器软件根目录/aligenie/认证文件。
  • 如果您开发的是 Springboot Web 项目，最后是可执行 jar 包在服务器运行，Springboot 项目内置有 Tomcat 插件，所以认证文件放置在项目中即可，文件存放路径为：resources/static/aligenie/认证文件。

平台的检测方法为：
获取您配置的 Webhook URL，取出URL中域名和端口号(如果有)，然后拼接上”aligenie/认证文件名.txt “访问这个路径，以返回的结果(认证文件的内容)作为依据，判断认证是否成功。
例如：

  1. 下载到的认证文件是 13f776873db7e9dfae87121bcec0712a.txt；
  2. 意图内配置的 Webhook URL 为 https://webhook-service.com/** ；
  3. 那么我们将访问 https://webhook-service.com/aligenie/13f776873db7e9dfae87121bcec0712a.txt；
  4. 将获取到的结果做校验，校验通过 Webhook URL 才能配置成功。

您可以手动访问认证文件的链接，看能否正确获取到认证文件的内容，即可确认认证文件是否配置成功。

若提示无效URL，说明URL格式不正确、无法访问或访问被拒绝。
若提示未正确获取到文件，说明在指定目录下没有认证文件或文件内容不正确。
当意图配置的Webhook URL是https链接时，如果服务器SSL证书无效，也会无法正确获取到文件。

PS: 每个 技能 只会生成一个认证文件，若开发者服务器上已经存放该文件，则无需再次下载认证文件；下载到的认证文件请不要修改文件名称和文件内容，以免认证失败。

2. Webhook服务搭建方式

无论您选择何种语言开发技能的 Webhook 服务，都需要准从平台规定的输入输出格式要求。详情参考【请求响应协议】。

对于使用 Java 语言开发的服务，我们有提供 SDK 帮助开发者转换请求响应对象。java开发SDK点此下载，或引入如下maven坐标下载

  1. <dependency>
  2.     <groupId>com.alibaba.da.coin</groupId>
  3.     <artifactId>semantic-execute-meta</artifactId>
  4.     <version>1.1.18-REALEASE</version>
  5. </dependency>

以天气查询为例的服务提供者的demo示例：

  1. @Controller   
  2. public class RequestController {
  4.     private static final Logger logger = LoggerFactory.getLogger(RequestController.class);
  6.     @Autowired
  7.     private WeatherHandle       weatherHandle;
  9.     /**
  10.      * skill开发者提供的技能执行路径地址，请求方式为POST请求
  11.      * 
  12.      * @param taskQuery
  13.      * @return
  14.      */
  15.     @RequestMapping(value = "/skill/weather", method = RequestMethod.POST)
  16.     public @ResponseBody ResultModel<TaskResult> getResponse(@RequestBody String taskQuery) {
  18.         /**
  19.          * 将开发者平台识别到的语义理解的结果（json字符串格式）转换成TaskQuery
  20.          */
  21.         logger.info("TaskQuery:{}", taskQuery.toString());
  22.         TaskQuery query = MetaFormat.parseToQuery(taskQuery);
  24.         /**
  25.          * 构建服务返回结果
  26.          */
  27.         ResultModel<TaskResult> resultModel = new ResultModel<TaskResult>();
  28.         try {
  29.             /**
  30.              * 调用天气服务执行并构建回复内容
  31.              */
  32.             TaskResult result = weatherHandle.execute(query);
  33.             resultModel.setReturnCode("0");
  34.             resultModel.setReturnValue(result);
  35.         } catch (Exception e) {
  36.             resultModel.setReturnCode("-1");
  37.             resultModel.setReturnErrorSolution(e.getMessage());
  38.         }
  40.         /**
  41.          * 直接返回ResultModel<TaskResult>对象就ok
  42.          */
  44.         return resultModel;
  45.     }
  47. }
  49.  // 天气服务执行，根据NLU理解的结果做相应处理并返回回复语句
  50. @Component
  51. public class WeatherHandleImpl implements WeatherHandle {
  53.     @Override
  54.     public TaskResult execute(TaskQuery taskQuery) {
  55.         logger.info("WeatherHandleImpl execute...");
  57.         //从请求中获取意图参数以及参数值
  58.         Map<String, String> paramMap = taskQuery
  59.                 .getSlotEntities()
  60.                 .stream()
  61.                 .collect(
  62.                         Collectors.toMap(slotItem -> slotItem.getIntentParameterName(),
  63.                                 slotItem -> slotItem.getStandardValue()));
  64.         logger.info("paramMap ：" + paramMap.toString());
  65.         //如果意图是询问空气质量，则执行空气质量逻辑
  66.         if (taskQuery.getIntentName().equals("空气质量")) {
  67.             return aqiQuery(taskQuery, paramMap);
  68.             //如果意图是询问天气情况，则执行天气查询逻辑
  69.         } else if (taskQuery.getIntentName().equals("天气查询")) {
  70.             return baseQuery(taskQuery, paramMap);
  71.         } else {
  72.             return null;
  73.         }
  74.     }
  76.     private TaskResult baseQuery(TaskQuery taskQuery, Map<String, String> paramMap) {
  77.         TaskResult result = new TaskResult();
  78.         try {
  79.             //请求服务并填充回复语句
  80.             List<NameValuePair> params = new ArrayList<NameValuePair>();
  81.             params.add(new BasicNameValuePair("areaName", paramMap.get("city")));
  82.             params.add(new BasicNameValuePair("date", DateUtil.getStartDate(paramMap.get("time"))));
  83.             String executeBody = httpGet(params);
  84.             String weather = getWeather(executeBody);
  85.             Map<String, String> properties = new HashMap<String, String>();
  87.             properties.put("city", paramMap.get("city"));
  88.             properties.put("time", paramMap.get("time"));
  89.             properties.put("weather", weather);
  90.             properties.put("temp_low", getTempLow(executeBody));
  91.             properties.put("temp_high", getTempHigh(executeBody));
  92.             properties.put("wind_direct", getWindDirect(executeBody));
  93.             properties.put("power", getPower(executeBody));
  94.             if (weather == null) {
  95.                 result.setReply("对不起，我现在只支持查询最近4天的天气");
  96.             } else {
  97.                 result.setReply(TemplateFillUtil
  98.                         .fillTemplate(
  99.                                 "@{city} @{time}天气 @{weather}，温度@{temp_low}到@{temp_high}度，@{wind_direct}@{power}",
  100.                                 properties));
  101.             }
  103.             result.setExecuteCode(ExecuteCode.SUCCESS);
  104.             result.setResultType(ResultType.RESULT);
  105.         } catch (Exception e) {
  106.             logger.info("query exception", e);
  107.             result.setExecuteCode(ExecuteCode.EXECUTE_ERROR);
  108.         }
  110.         return result;
  111.     }
  112. }
  1. 在您开发好开发 Webhook 服务后，将此 Web 服务的 URL 地址填入意图的 回复逻辑 中。
  2. 当测试技能时开放平台意图逻辑引擎会将语义理解之后的结果以 http(s) post 的方式调用此服务。
  3. 您也可以自定义header字段，这样在发送 post 请求时，请求头中会携带您定义的信息。
  4. 服务拿到语义理解的结果之后就可以进行相应的处理，并按照意图逻辑规定的方式返回处理后的结果。