# 技能标准请求
注意
- 该文档中,除了
IntentRequest
外,其他均只适用于技能协议v2.1,v2.0中没有该请求。 IntentRequest
在v2.1中有字段更新。
标准请求是所有技能都需要实现的请求,这些请求中包含请求协议_2.1中提到的所有字段:version, session, context, request。
标准请求包含:
- LaunchRequest: 用户通过入口词“打开
{技能名称}
”进入你的技能时,你将会收到这个请求。 - TextRequest: 在你的技能中,用户的语音请求未经过iFLYOS解析直接请求你的服务器时,你将会收到这个请求。
- IntentRequest: 用户的语音请求经过iFLYOS解析后请求你的服务器时,你将会收到这个请求。
- SessionEndedRequest: 用户主动退出技能结束会话时,你将会收到这个请求。
# LaunchRequest
# 消息示例
{
"type": "LaunchRequest",
"requestId": "f78b7d68...",
"timestamp": "2018-08-06T16:13Z ",
}
# 参数说明
参数 | 描述 | 类型 | 必须出现 |
---|---|---|---|
type | 请求类型,这里取值 LaunchRequest | String | 是 |
requestId | 代表请求的唯一标识符。 | String | 是 |
timestamp | 请求时间戳,以ISO 8601格式发送 | String | 是 |
# TextRequest
# 消息示例
{
"type": "TextRequest",
"requestId": "f78b7d68...",
"timestamp": "2018-08-06T16:13Z ",
"query": {
"type": "TEXT",
"original":"今天天气怎么样?"
}
}
# 参数说明
参数 | 描述 | 类型 | 必须出现 |
---|---|---|---|
type | 请求类型,这里取值 TextInputRequest | String | 是 |
requestId | 代表请求的唯一标识符。 | String | 是 |
timestamp | 请求时间戳,以ISO 8601格式发送 | String | 是 |
query | 请求信息。 - type:请求类型,取值 TEXT - original:用户语音经过IVS理解后生成的文本 | String | 是 |
# IntentRequest
当用户命中了你的技能中定义的意图时,你将会收到请求。
# 消息示例
{
"type": "IntentRequest",
"requestId": "TbXlwz-F86pYnD0VwWbqauUDRwiNOU5i70DgS54E8wFCqpK2ku9bGYKzCGfm1mNw",
"timestamp": "2018-09-05T02:59:45.503551Z",
"dialogState": "STARTED",
"query": {
"type": "TEXT",
"original": "下一首"
},
"intent": {
"name": "string",
"score": float,
"confirmationStatus": "string",
"slots": {
"SlotName": {
"name": "SlotName",
"value": "周董",
"normValue": "周杰伦",
"moreValue": ["槽值1","槽值2"],
"confirmationStatus": "string",
}
}
}
}
# 参数说明
参数 | 描述 | 类型 | 必须出现 |
---|---|---|---|
type | 请求类型,这里取值 IntentRequest | string | 是 |
requestId | 代表请求的唯一标识符。 | string | 是 |
timestamp | 请求时间戳,以ISO 8601格式发送 | string | 是 |
dialogState | 当前会话状态。取值: STARTED 开始,IN_PROGRESS 进行中,COMPLETED 完成(意图收集和确认了所有必填槽位,同时如果意图有需求也已经一并确认了) | string | 是 |
query | 请求信息。 - type: 请求类型,取值 TEXT - original: 用户语音经过ivs理解后生成的文本 | object | 是 |
intent | 意图信息 | object | 是 |
intent.name | 意图名称,你的技能中定义的意图名称 | string | 是 |
intent.score | 意图置信度。iFLYOS语义理解之后对用户语料命中该意图的置信度。 | string | 是 |
intent.confirmationStatus | 意图确认状态。取值:NONE 未确认,CONFIRMED 确认,DENIED 否认。当dialogState 为COMPLETED 时,此处状态为CONFIRMED 或DENIED 。当意图不需要确认时,该字段不出现 | string | 否 |
intent.slots | 意图中的槽位信息,以key-value结构展示,key为槽名,value为槽值。只显示解析出来的槽。IVS开放意图此项不显示;意图中未定义词槽,该字段不出现。 | array | 否 |
# slots 参数说明
参数 | 描述 | 类型 | 必须出现 |
---|---|---|---|
[slotName].name | 槽位名称 | string | 是 |
[slotName].value | 用户语料经过语义理解后解析出来的槽值,是用户语料中包含的词,如“周董”。 | string | 是 |
[slotName].normValue | 用户语料经过语义理解后解析出来并规整后的槽值,是用户语料中包含的词,如“周杰伦”。可能会和value 的值一样 | string | 是 |
[slotName].moreValue | 用户语料经过语义理解后解析出来的槽值,当用户语料中包含该词槽的多个槽值时,出现该字段,以数组形式展示。比如用户说“我要买苹果,香蕉和橘子”,则value ="苹果",moreValue =["香蕉","橘子"]。moreValue 取值来源于用户语料中包含的槽值的词条名(normValue ) | array | 否 |
[slotName].confirmationStatus | 槽确认状态。取值:NONE 未确认,CONFIRMED 确认,DENIED 否认。当词槽非必填时,该字段不出现。 | string | 否 |
开放意图
IntentName | 用户语料 | 用户意图 | Response建议 |
---|---|---|---|
ivs_next_intent | 下一首;切歌;切换到下一首 | 播放下一首 | Response中包含AudioPlayer.Play 指令,播放下一首歌曲 |
ivs_previous_intent | 上一首;回到上一首;切换到上一首 | 播放上一首 | Response中包含AudioPlayer.Play 指令,播放上一首歌曲 |
ivs_pause_intent | 暂停;停下来;暂停一下 | 暂停播放 | Response中包含AudioPlayer.Stop 指令,停止播放,并通过后续接到的AudioPlayer.PlaybackStopped 请求记录播放进度 |
ivs_resume_intent | 继续播放;接着播 | 继续播放 | Response中包含AudioPlayer.Play 指令,从上一个接到的AudioPlayer.PlaybackStopped 请求记录的播放进度处开始播放 |
ivs_inquire_media_intent | 现在播的是什么;当前播放节目是什么;这是什么歌 | 查询当前播放的音频的名称 | Response中通过outputSpeech 传输回复文本 |
ivs_inquire_artist_intent | 这是谁的歌;现在在播谁的节目 | 查询当前音频作者 | Response中通过outputSpeech 传输回复文本 |
# SessionEndedRequest
用户触发了结束会话的操作时发送。
消息示例
{
"type": "SessionEndedRequest",
"requestId": "f78b7d68...",
"timestamp": "2018-08-06T16:13Z ",
"reason": "ERROR",
"error": {
"type": "INVALID_RESPONSE",
"message": "无效回复"
}
}
参数说明
参数 | 描述 | 类型 | 必须出现 |
---|---|---|---|
type | 请求类型,这里取值 SessionEndedRequest | String | 是 |
requestId | 代表请求的唯一标识符。 | String | 是 |
timestamp | 请求时间戳,以ISO 8601格式发送 | String | 是 |
reason | 结束会话的原因,取值: - USER_INITIATED :用户明确结束了会话; - ERROR :错误导致会话结束; - EXCEEDED_MAX_REPROMPTS :用户无输入或多次输入无法理解 | String | 是 |
error | 当结束原因为ERROR 时,出现该字段。包含:- type: 错误类型,取值: - INVALID_RESPONSE ,无效回复- DEVICE_COMMUNICATION_ERROR ,设备通讯错误- INTERNAL_ERROR ,内部错误- message: 错误信息 | Object | 否 |