AliGenie - 智能应用开放平台

智能应用开放平台

智能应用

APP

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

1. 认证文件校验

目前开放平台将对开发者填写的 Webhook 服务地址做真实性校验（检测服务地址的有效性和开发者对服务地址是否有权限）。

在配置 Webhook URL 前请先下载技能的认证文件，并将认证文件配置在服务器中供平台检测。

认证文件的配置方法为：

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

平台的检测方法为：

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

例如：

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

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

若提示无效URL，说明URL格式不正确、无法访问或访问被拒绝。

若提示未正确获取到文件，说明在指定目录下没有认证文件或文件内容不正确。

当意图配置的Webhook URL是https链接时，如果服务器SSL证书无效，也会无法正确获取到文件。

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

2. Webhook服务搭建方式

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

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

<dependency>
    <groupId>com.alibaba.da.coin</groupId>
    <artifactId>semantic-execute-meta</artifactId>
    <version>1.1.18-REALEASE</version>
</dependency>

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

@Controller   
public class RequestController {

    private static final Logger logger = LoggerFactory.getLogger(RequestController.class);

    @Autowired
    private WeatherHandle       weatherHandle;

    /**
     * skill开发者提供的技能执行路径地址，请求方式为POST请求
     * 
     * @param taskQuery
     * @return
     */
    @RequestMapping(value = "/skill/weather", method = RequestMethod.POST)
    public @ResponseBody ResultModel<TaskResult> getResponse(@RequestBody String taskQuery) {

        /**
         * 将开发者平台识别到的语义理解的结果（json字符串格式）转换成TaskQuery
         */
        logger.info("TaskQuery:{}", taskQuery.toString());
        TaskQuery query = MetaFormat.parseToQuery(taskQuery);

        /**
         * 构建服务返回结果
         */
        ResultModel<TaskResult> resultModel = new ResultModel<TaskResult>();
        try {
            /**
             * 调用天气服务执行并构建回复内容
             */
            TaskResult result = weatherHandle.execute(query);
            resultModel.setReturnCode("0");
            resultModel.setReturnValue(result);
        } catch (Exception e) {
            resultModel.setReturnCode("-1");
            resultModel.setReturnErrorSolution(e.getMessage());
        }

        /**
         * 直接返回ResultModel<TaskResult>对象就ok
         */

        return resultModel;
    }

}

 // 天气服务执行，根据NLU理解的结果做相应处理并返回回复语句
@Component
public class WeatherHandleImpl implements WeatherHandle {

    @Override
    public TaskResult execute(TaskQuery taskQuery) {
        logger.info("WeatherHandleImpl execute...");

        //从请求中获取意图参数以及参数值
        Map<String, String> paramMap = taskQuery
                .getSlotEntities()
                .stream()
                .collect(
                        Collectors.toMap(slotItem -> slotItem.getIntentParameterName(),
                                slotItem -> slotItem.getStandardValue()));
        logger.info("paramMap ：" + paramMap.toString());
        //如果意图是询问空气质量，则执行空气质量逻辑
        if (taskQuery.getIntentName().equals("空气质量")) {
            return aqiQuery(taskQuery, paramMap);
            //如果意图是询问天气情况，则执行天气查询逻辑
        } else if (taskQuery.getIntentName().equals("天气查询")) {
            return baseQuery(taskQuery, paramMap);
        } else {
            return null;
        }
    }

    private TaskResult baseQuery(TaskQuery taskQuery, Map<String, String> paramMap) {
        TaskResult result = new TaskResult();
        try {
            //请求服务并填充回复语句
            List<NameValuePair> params = new ArrayList<NameValuePair>();
            params.add(new BasicNameValuePair("areaName", paramMap.get("city")));
            params.add(new BasicNameValuePair("date", DateUtil.getStartDate(paramMap.get("time"))));
            String executeBody = httpGet(params);
            String weather = getWeather(executeBody);
            Map<String, String> properties = new HashMap<String, String>();

            properties.put("city", paramMap.get("city"));
            properties.put("time", paramMap.get("time"));
            properties.put("weather", weather);
            properties.put("temp_low", getTempLow(executeBody));
            properties.put("temp_high", getTempHigh(executeBody));
            properties.put("wind_direct", getWindDirect(executeBody));
            properties.put("power", getPower(executeBody));
            if (weather == null) {
                result.setReply("对不起，我现在只支持查询最近4天的天气");
            } else {
                result.setReply(TemplateFillUtil
                        .fillTemplate(
                                "@{city} @{time}天气 @{weather}，温度@{temp_low}到@{temp_high}度，@{wind_direct}@{power}",
                                properties));
            }

            result.setExecuteCode(ExecuteCode.SUCCESS);
            result.setResultType(ResultType.RESULT);
        } catch (Exception e) {
            logger.info("query exception", e);
            result.setExecuteCode(ExecuteCode.EXECUTE_ERROR);
        }

        return result;
    }
}

在您开发好开发 Webhook 服务后，将此 Web 服务的 URL 地址填入意图的 回复逻辑 中。
当测试技能时开放平台意图逻辑引擎会将语义理解之后的结果以 http(s) post 的方式调用此服务。
您也可以自定义header字段，这样在发送 post 请求时，请求头中会携带您定义的信息。
服务拿到语义理解的结果之后就可以进行相应的处理，并按照意图逻辑规定的方式返回处理后的结果。