一、产品介绍

基于http协议API请求DUI全链路产品，获得对话交互结果。

1.1 适用场景

• 轻量级嵌入式设备，基于协议开发
• 采用云对云的方式，使用DUI全链路产品，基于协议开发
• 其他特殊场景，需要基于协议开发
• 使用文本请求对话
• 设置系统级或技能级配置

1.2 使用限制

• 需要先前往控制台创建全链路产品，并且将产品成功发布，才能正常使用基于http协议的API
• 本接口只支持文本输入

二、接入说明

2.1 接入前的准备

• 登录DUI控制台
• 创建全链路产品
• 进行产品配置
• 添加技能
• 进行产品测试
• 配置授权
• 发布产品

2.2 连接参数

本API正式环境的地址是https://dds.dui.ai/dds/v2/[分支号]，其中[分支号]是DUI控制台分支管理页面的内容，需要在控制台上进行选择；如下图所示： 在产品详情页的发布管理页面，点击【分支管理】，进入分支管理界面，获取分支号。

 

2.2.1连接上需要携带的公共参数

连接上需要携带的授权参数，包含了授权参数，授权有两种场景，一种是设备对接云，一种是云对云；

2.2.2设备对接云端API的授权参数

获取deviceName，需要走设备激活流程，具体步骤见设备激活接口

2.2.3云端对接云端的授权参数

2.2.4一条完整的云端对接云端的连接示例

https://dds.dui.ai/dds/v2/test?productId=278578090&apikey=0ddddeeeeeeeeeeee88888888260c8ab

2.2.5在以下情况下建立连接会失败

• 产品没有发布
• 产品分支号没有对应已经发布过的产品版本
• 授权参数不正确，服务端鉴权不通过

2.3 发送文本请求对话

2.3.1 请求格式

POST /dds/v2/test?productId=278578090&apikey=0ddddeeeeeeeeeeee88888888260c8ab HTTP/1.1
Host: dds.dui.ai
Content-Type: application/json
Content-Length: N
 
{
    "topic":"nlu.input.text", // 必选
    "recordId":"12341asdfa", // 可选，uuid，请求标识
    "sessionId":"1234efaf", // 可选，首轮不带此参数，非首轮必须带此参数
    "refText": "ARE YOU READY FOR LOVE", // 必选，请求文本
    "context":{                            // 可选
        "skill":{                         
            "skillId": "DUIddeeeeeeee", // 可选, 跳过skill dispatch, 用于指定skillId
            "task": "英译中"                // 可选, 只有在非首轮时才可能用到, 用于指定task, 客户端上一轮使用了该skill下的哪个task
        }
    }
}

2.3.2请求参数

2.3.3 响应格式

HTTP/1.1 200
Content-Type: application/json
Content-Length: N
 
{
    "dm":{                                             // 对话返回的结果, 同websocket协议的返回结果
        "task":"骂人",                                 // 任务名称
        "taskId":"5b7527da6e47e4000189e3e1",          // 任务uuid标识
        "intentName":"被骂傻",                         // 意图名称
        "intentId":"5ae17d13d6e20b000185b9e3",        // 意图uuid标识
        "command":{
            "api":"chatting",                         // 调用本地API接口名
            "param":{                                 // 调用本地API接口参数
                "rawId":"p_065-p_066-p_067",
                "answer":"还好吧，别人都说我很聪明呢-听着情况好像不妙啊-你被我愚蠢的假象迷惑了吧，其实我聪明的很呢"
            }
        },
        "shouldEndSession":true,                      // 布尔值，表示是否结束对话
        "runSequence":"nlgFirst",                     // 枚举值，commandFirst和nlgFirst；nlgFirst表示先播合成音，commandFirst表示先执行本地命令
        "nlg":""                                      // 对话回复的自然语言文本
    },
    "skill": "闲聊",                                   // 命中的技能名
    "skillId":"DUIddeeeeeeee",                        // 命中的技能uuid标识
    "recordId":"DUIDEVf4fc46c52513a282deee8cfaa3abe02e",    // 请求uuid标识
    "contextId":"01324e00c1d8484192e4413b98d402f8",         // 兼容性字段，准备废弃
    "sessionId":"10382109381209381093810923812093"          // 关联对话上下文uuid标识
}

2.3.4 响应结果参数

 

参数名	含义
dm.task	任务名称
dm.taskId	任务 uuid 标识
dm.intentName	意图名称
dm.intentId	意图 uuid 标识
dm.command	调用本地 API 指令
dm.command.api	调用本地 API 接口名
dm.command.param	调用本地 API 接口参数
dm.shouldEndSession	布尔值，表示是否结束对话
dm.runSequence	枚举值，commandFirst和nlgFirst；nlgFirst表示先播合成音，commandFirst表示先执行本地命令
dm.nlg	对话回复的自然语言文本
skillId	技能唯一标识
recordId	请求标识

2.4 做系统级配置

自定义配置配合技能开发使用生效，具体请参照 配置对话回复 中的 资源查询结果引用——$参数名称$。

2.4.1 请求格式

POST /dds/v2/test?productId=278578090&apikey=0ddddeeeeeeeeeeee88888888260c8ab HTTP/1.1
Host: dds.dui.ai
Content-Type: application/json
Content-Length: N
 
 
{
    "topic":"system.settings",    // 必选，表示系统级配置
    "settings":[                  // 必选
        {
            "key":"location",     // 配置的key,类型是字符串
            "value":{             // 配置的值,类型是字符串或者json
                "longitude":"x",
                "latitude":"x",
                "address":"x",
                "city":"x",
                "time":"2018-08-22T12:46:16+0800"
            }
        }
    ]
}

2.4.2 请求参数

 

2.4.3 响应格式

HTTP/1.1 200
Content-Type: application/json
Content-Length: 2
 
 
{}

2.5 做技能级配置

2.5.1 请求格式

POST /dds/v2/test?productId=278578090&apikey=0ddddeeeeeeeeeeee88888888260c8ab HTTP/1.1
Host: dds.dui.ai
Content-Type: application/json
Content-Length: N
 
{
    "topic":"skill.settings",      // 必选，表示技能级配置
    "skillId": "DUIddeeeeeeee",    // 必选，技能uuid标识
    "settings":[
        {
            "key":"key1",          // 配置的key,类型是字符串
            "value": "value1"      // 配置的值,类型是字符串或者json
        }
    ]
}

2.5.2 请求参数

 

参数名	含义	是否必须	取值示例
topic	表示技能级配置	是	必须为 "skill.settings"
skillId	技能 uuid 标识	是	DUIddeeeeeeee
settings	配置信息	是
settings.key	配置的key,类型是字符串	否	key1
settings.value	配置的值,类型是字符串或者json	否	value1

 

2.5.3 响应格式

HTTP/1.1 200
Content-Type: application/json
Content-Length: 2
 
 
{}

三、示例DEMO

查看java示例

查看Python示例