API接口编写说明

一. API接口

1.1 web API

1.1.1 简介

web API 别名webhook,是一个方法为POST、请求响应body格式为json的HTTP/HTTPS接口,供开放者在DUI平台使用内容资源,其中json的格式为key、value对。

1.1.2 API配置

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


返回结果

返回的json可以通过约定的格式适配内置控件,内置控件包括:内容卡片控件、列表控件、多媒体控件、内嵌网页控件,具体描述见下文。

1.2 Function

Function类似Amazon Lambda,相当于开发者实现了一段运行在DUI服务器上的代码。开发者可以在Function里实现请求原始API和数据格式的转换。目前Function支持Python和Node.js语言。

Function编写示例

1.3 Native API

1.3.1 简介

native API特指使用本地代码实现的接口,比如在Android上使用Java代码实现的接口,Linux上使用C语言实现的接口。(在DUI SDK里有实现Native API的示例,您可以前往SDK下载页下载所需的SDK包。) 由于需要一次服务端到本地端的网络通信,建议只有在Web API或Function不能满足需求时再使用。

1.3.2 native api 响应

Minion

当您在DUI平台上定制了native api之后,可以使用如下的方式在您的工程中做实现.
类似于Android的广播接收器,您可以在需要的地方注册和注销Native Api Observer, 同一个Native Api Observer可以处理多个native api。

command

// 注册
DDS.getInstance().getAgent().subscribe(new String[]{"query_battery"}, nativeApiObserver);
 
// 注销
DDS.getInstance().getAgent().unSubscribe(nativeApiObserver);
 
private NativeApiObserver nativeApiObserver = new NativeApiObserver() {
    @Override
    public void onQuery(final String nativeApi, final String data) {
        if (nativeApi.equals("query_battery")){
            JSONObject jsonData = new JSONObject(data);
            String intentName = jsonData.optString("intentName");
            // 执行查询电量操作
            String battery = DeviceUtil.getBattery();
            DDS.getInstance().getAgent().feedbackNativeApiResult(nativeApi, new TextWidget().setText(battery));
        }
    }
};

备注:

1.每个onQuery方法执行时,需要调用feedbackNativeApi Result来向DUI平台返回执行结果,表示一个native api执行结束
2.native api的执行超时时间为10s

二. 控件数据格式

编写的API格式需要能对接上DUI的控件。

2.1 内容卡片控件

2.1.1. 参数列表

属性 必填(Y/N) 说明
title N 内容卡片标题
subTitle N 内容卡片子标题
label N 内容卡片标签
imageUrl N 内容卡片图片资源地址
linkUrl N 内容卡片资源地址
extra N 用户自定义参数,透传给用户

2.1.2 示例代码

{
    "title": "card-title",
    "subTitle":"card-sub-title",
    "label":"card-label",
    "imageUrl":"URL of the image to be shown",
    "linkUrl":"URL of the attribute to be associated with the card",
    "extra": {
        "key1": "val1",
        "key2": "val2"
    }  
}

2.2 列表控件

2.2.1. 参数列表

参数名 必填(Y/N) 说明
count Y data字段内数据列表个数
content Y 查询返回的数据列表,每个子项是个内容卡片,如:Minion

2.2.2 示例代码

{
    "count": 2,
    "content": [
        {
            "title": "独墅湖图书馆东",
            "extra": {
                "L": 123.3,
                "H": 323.4
            }
        },
        {
            "title": "独墅湖图书馆南",
            "extra": {
                "L": 33213.,
                "H": 666.3
            }
        }
    ]
}

2.3 多媒体控件

2.3.1. 参数列表

参数名 必填(Y/N) 说明
count Y 资源列表个数
content Y 多媒体资源列表,每个子项是内容卡片,如:Minion

2.3.2 示例代码

{
    "count": 2,
    "widgetName": "播放列表",
    "content": [
        {
            "title": "忘情水",
            "subTitle": "来生缘",
            "label":"刘德华",
            "imageUrl":"https://liu-de-hua.png",
            "linkUrl":"https://wang-qing-shui.mp3"
            "extra": {
                "resType": "mp3"
            }
        },
        {
            "title": "爱你一万年",
            "subTitle": "来生缘",
            "label":"刘德华",
            "imageUrl":"https://liu-de-hua.png",
            "linkUrl":"https://ai-ni-yi-wan-nian.wav"
            "extra": {
                "resType": "wav"
            }
        }
    ]
}

2.4 内嵌网页控件

2.4.1. 参数列表

参数名 必填(Y/N) 说明
url Y 内嵌网页url资源地址
extra N 用户自定义参数,透传给用户。开发者也可以在定制平台引用:$exra.key1$

2.4.2 示例代码

{
    "url": "URL of the web widget",
    "extra": {
        "key1": "val1",
        "key2": "val2"
    }
}

2.5 自定义控件

2.5.1. 参数列表

参数名 必填(Y/N) 说明
extra N 用户自定义参数,透传给用户

2.5.2 示例代码

{
    "extra": {
        "key1": "val1",
        "key2": "val2"
    }
}