技能对DuerOS的响应

摘要

技能通过HTTPS(调试环境可使用HTTP/1)协议返回响应数据,数据格式为json。技能返回的响应数据总大小不能超过24KB。 以下定义了技能在处理完请求后,返回给DuerOS的响应消息格式。

响应消息样例

{
    "version" : "2.0",
    "context" : {
        "intent" : {
            "name" : "{{STRING}}",
            "slots" : {
                "{{STRING}}" : {
                    "name" : "{{STRING}}",
                    "value" : "{{STRING}}",
                }
            }
        },
        "expectResponse" : [
        {
            "type": "{{STRING}}",
            "text": "{{STRING}}",
            "slot": "{{STRING}}",
        }],

        "storage": {
            "behavior": "{{ENUM}}",
            "updates": [{
                "key": "{{STRING}}",
                "value": {},
                "timeout": {{INT}}
         }
    },

    "session" : {
        "attributes" : { 
            "{{STRING}}": "{{STRING}}"
        },
    },
    "response" : {
        "outputSpeech" : {
            "type" : "{{STRING}}",
            "text" : "{{STRING}}",
            "ssml" : "{{STRING}}",
        },
        "reprompt" : {
            "outputSpeech" : {
                "type" : "{{STRING}}",
                "text" : "{{STRING}}",
                "ssml" : "{{STRING}}",
            }
        },
        "card" : {},
        "directives" : [],
        "expectSpeech": {{BOOLEAN}},
        "shouldEndSession" : {{BOOLEAN}}
    }
}

响应参数说明

  • version
    • 协议版本,当前为“2.0”。
  • context
    • 技能返回给DuerOS的信息,用于反馈技能对本次请求的意图理解。
  • session
    • 会话信息。
  • response
    • 响应内容,DuerOS将会把这些内容转换成对应的设备端指令或DuerOS定义的操作。

context参数说明

用于反馈给DuerOS的intent结果;当技能结合自己的资源,对本次query有更加合理的理解时,可以修改对应槽位并返回该信息,DuerOS会在后续的query中优化意图解析模型。

  • intent
    • 技能认为对本次query更加合理的意图解析。
  • intent.name
    • 意图名称。通过技能开放平台定义的意图,或来自系统意图。
  • intent.slots
    • 意图中的槽位。slot结构是key-value结构,key为slot名字,value为slot槽位信息。
  • intent.slots.name
    • 槽位名称。
  • intent.slots.values
    • 槽位值,表示一个槽位中解析出来的多个值。例如我想听张学友、刘德华和黎明的歌。此时values的size是3,值分别是张学友、刘德华和黎明。
  • expectResponse参数说明 技能推测用户可能的回复。当技能将用户可能的回复内容提供给DuerOS时,有助于DuerOS在下一轮对话中提高语音识别能力。
  • expectResponse.type
    • 技能期待用户回复内容的类型,取值如下:
      • PlainText:普通文本类型。
      • Slot:槽位类型。
  • expectResponse.text
    • 技能期待用户的回复内容,回复内容是普通文本,长度不超过256个字符。当type取值为PlainText时,该字段为必选字段。
  • expectResponse.slot
    • 当技能期待用户针对特定槽位进行回复时,此时应填写对应槽位的名称,长度不超过256个字符。当type取值为Slot时,该字段为必选字段。如在必填槽位追问的场景中,技能期待用户回复的内容就是针对特定槽位的。
  • storage参数说明
    • DuerOS平台提供给bot的key-value存储接口。
  • storage.behavior
    • 定义DuerOS平台在存储session数据时的行为
      • MERGE:DuerOS负责merge当前已经存储的数据和本次请求需要存储的数据。对于已经存在的key,使用本次数据覆盖之前的数据;对于新增的key,存储对应的数据。
      • REPLACE_ALL:DuerOS平台负责清除之前存储的数据,并存储本次的数据。
  • storage.updates
    • 需要存储的数据信息。存储信息结构是key-value结构,key为数据键名,value为数据值。
    • 注意:目前允许存储的信息最大为128k。
  • storage.updates[].key
    • 需要DuerOS平台存储的数据键值。
  • storage.updates[].value
    • 需要DuerOS平台存储的数据内容。
  • storage.updates[].timeout
    • 当前存储内容的有效时间,单位为秒,目前最大值是5 x 24 x 60 x 60 s,即5天。
    • 如果timeout > 0,代表当前存储内容的过期时间。
    • 如果timeout <= 0,代表删除当前键值对应的内容。
    • 如果该值不存在,默认表示存储该内容10分钟。

session参数说明

  • session.attributes
    • 技能存储在DuerOS的临时数据。
    • 如果本次session不结束,那么在下一个发送给技能的请求中,在session.attributes字段会携带这些临时数据下发至技能。

response参数说明

  • outputSpeech
    • 表示本次返回结果中需要播报的语音信息
  • outputSpeech.type
    • TTS类型。取值如下:
      • PlainText:普通文本。
      • SSML:一种结构化语言,用于辅助描述语音发音声调。
    • text
      • 普通文本内容。当type取值为PlainText时,该字段为必选字段。长度不能超过256个字符。
    • ssml
      • 结构化描述内容,详见ssml文档。当type为SSML时,该字段为必选字段。长度不能超过256个字符。
  • reprompt
    • 在需要用户输入时,如果用户离开了,麦克风没有进行语音输入,或用户输入的语音请求系统无法解析成技能的任何意图,则播报reprompt内容。reprompt.outputSpeech参数定义与上述outputSpeech的定义一致。
  • card
  • directives
  • expectSpeech
    • 在会话进行过程中,技能是否需要用户进行对话响应。
    • 该字段可选,并且仅在shouldEndSession为false时有效。
      • true:表示技能需要用户进行对话响应,设备端上打开麦克风聆听用户的语音。
      • false:表示技能不需要用户进行对话响应,设备端上关闭麦克风。
  • shouldEndSession
    • 本次会话结束标识。
      • true: 表示本次会话结束,技能退出。
      • false:表示会话没有结束,此时可以配置expectSpeech字段。如果没有配置expectSpeech字段,表示技能需要用户进行对话响应,设备端上打开麦克风聆听用户的语音。

代码示例

response样例

{
    "version": "2.0",
    "session": {
        "attributes": {}
    },
    "context": {
        "intent" : null
    },
    "response": {
        "outputSpeech": {
            "type": "PlainText",
            "text": "请问您在哪个城市?"
        },
        "reprompt": {
            "outputSpeech": {
                "type": "PlainText",
                "text": "请问您在哪个城市?"
            }
        },
        "directives" : [{
            "type": "Dialog.ElicitSlot",
            "slotToElicit": "city",
            "updatedIntent": {
                "name": "personal_income_tax.inquiry",
                "confirmationStatus": "NONE",
                "slots": {
                    "compute_type": {
                        "name": "compute_type",
                        "value": "个税",
                        "confirmationStatus": "NONE"
                    },
                    "inquiry": {
                        "name": "inquiry",
                        "value": "查一下",
                        "confirmationStatus": "NONE"
                    }
                 }
            }
        }],
        "shouldEndSession" : false
    }
}