标准请求

摘要

在用户通过语音输入后，DuerOS会对语音请求进行识别和理解，并将理解结果发送给技能。以下定义了技能的格式。标准请求包括三类，分别是LaunchRequest、IntentRequest和SessionEndedRequest。

LaunchRequest

“打开技能”的请求会被解析为LaunchRequest。例如“小度小度，打开闹钟”，将会发送请求给名称为“闹钟”的技能。

消息样例

{
    "type": "LaunchRequest",
    "requestId": "{{STRING}}",
    "timestamp": "{{STRING}}"
}

参数说明

• type
  • 请求类型，即字符串"LaunchRequest"。
• requestId
  • 标识本次请求的唯一ID。如果有问题反馈，可以附带提供给DuerOS开发人员。
• timestamp
  • 请求时间戳，单位是秒，是一个全部是数字的字符串。

示例

{
    "version": "2.0",
    "session": {
        "new": true,
        "sessionId": "b393ef84-e77c-425f-964e-e62ee3c7b338",
        "attributes": {}
    },
    "context": {
        "System": {
            "application": {
                "applicationId": "personal_income_tax"
            }
        }
    },
    "request": {
        "type": "LaunchRequest",
        "requestId": "d407e869-55f7-4681-b49f-8a41bc196da0",
        "timestamp": "1499790258"
    }
}

IntentRequest

以下两种情况，请求会被DuerOS转换为IntentRequest。

• 技能还没被调起，用户语音请求“打开技能，帮我查询天气” 此请求会被解释为查询天气的IntentRequest，session.new的值为true。
• 技能已经被调起，用户与技能在多轮对话中，用户请求 “帮我查询天气” 此请求会被解释为查询天气的IntentRequest，session.new的值为false。

消息样例

{
    "type": "IntentRequest",
    "requestId": "{{STRING}}",
    "timestamp": "{{STRING}}",
    "query": {
        "type": "{{STRING}}",
        "original": "{{STRING}}"
    },
    "dialogState": "{{STRING}}",
    "intents": [{
        "name": "{{STRING}}",
        "slots": {
            "{{STRING}}": {
                "name": "{{STRING}}",
                "value": "{{STRING}}",
                "values": ["{{STRING}}"],
                "confirmationStatus": "{{STRING}}"
            }
        },
        "confirmationStatus": "{{STRING}}"
    }],
}

参数说明

• type
  • 请求类型，即字符串"IntentRequest"。
• requestId
  • 标识本次请求的唯一ID。如果有问题反馈，可以附带提供给DuerOS开发人员。
• timestamp
  • 请求时间戳，单位是秒，是一个全部是数字的字符串。
• query
  • 本次请求信息。
• query.type
  • 请求类型，取值如下：
    • TEXT
      • 本次语音请求经过DuerOS理解后是一个文本请求。
• query.original
  • 本次语音请求经过DuerOS理解后生成的文本。
• dialogState
  • 当前会话状态，取值如下：
    • STARTED
      • 开始。
    • IN_PROGRESS
      • 进行中。
    • COMPLETED
      • 本轮对话的意图已经收集和确认了所有必要槽位，同时如果意图有需求也已经一并确认了。
• intents
  • 本次语音请求被DuerOS解析后生成的意图。DuerOS可能解析出一个或多个意图，这些意图按照概率可能性由大到小排序。
• intents.name
  • 意图名称。通过技能开放平台定义的意图，或来自系统意图。
• intents.slots
  • 意图中的槽位。slot结构是key-value结构，key为slot名字，value为slot槽位信息。
• intents.confirmationStatus
  • 意图确认状态：当确认状态为CONFIRMED或DENIED时，dialogState设置为COMPLETED。意图状态取值如下：
    • NONE: 未确认
    • CONFIRMED: 确认
    • DENIED: 否认
• intents.slots.name
  • 槽位名称。
• intents.slots.value
  • 槽位值。表示解析出的槽位值，如果解析出有多个，这里是第一个值。
• intents.slots.values
  • 槽位值，表示一个槽位中解析出来的多个值。例如我想听张学友、刘德华和黎明的歌。此时values的size是3，值分别是张学友、刘德华和黎明。
• intents.slots.confirmationStatus
  • 槽位确认状态，取值如下：
    • NONE: 未确认
    • CONFIRMED: 确认
    • DENIED: 否认

示例

{
    "version": "2.0",
    "session": {
        "new": false,
        "sessionId": "b393ef84-e77c-425f-964e-e62ee3c7b338",
        "attributes": {}
    },
    "context": {
        "System": {
            "application": {
                "applicationId": "personal_income_tax"
            }
        }
    },
    "request": {
        "type": "IntentRequest",
        "requestId": "1927e048-f8bf-4201-9c97-cf2fba5f992a",
        "timestamp": "1499169543",
        "query": {
            "type": "TEXT",
            "original": "帮我查一下个税"
        },
        "intents": [
            {
                "name": "personal_income_tax.inquiry",
                "confirmationStatus": "NONE",
                "slots": {
                    "compute_type": {
                        "name": "compute_type",
                        "values": ["个税"],
                        "confirmationStatus": "NONE"
                    },
                    "inquiry": {
                        "name": "inquiry",
                        "values": ["查一下"],
                        "confirmationStatus": "NONE"
                    }
                }
            }
        ]
    }
}

SessionEndedRequest

如果本次session不是技能主动结束的（也就是技能被动结束的，被动结束原因见reason字段），那么DuerOS会向技能发送SessionEndedRequest。

消息样例

{
  "type": "SessionEndedRequest",
  "requestId": "{{STRING}}",
  "timestamp": "{{STRING}}",
  "reason": "{{STRING}}",
  "error": {
      "type": "{{STRING}}",
      "message": "{{STRING}}"
  }
}

参数说明

• type
  • 请求类型，即字符串"SessionEndedRequest"。
• requestId
  • 标识本次请求的唯一ID。如果有问题反馈，可以附带提供给DuerOS开发人员。
• timestamp
  • 请求时间戳，单位是秒，是一个全部是数字的字符串。
• reason
  • session被动结束的原因，一共有三种原因：
    • USER_INITIATED：用户直接说“退出”。
    • EXCEEDED_MAX_REPROMPTS：用户无输入或多次输入无法理解。
    • ERROR：系统错误，详细信息见error字段。
• error
  • type：错误类型，可能的值如下：
    • INVALID_RESPONSE: 技能返回了无效的响应，例如以下情况：
      • 技能响应数据量超过24KB。
      • 技能在request的dialogState为COMPLETED时仍然发送Dialog.Delegate指令等。
    • DEVICE_COMMUNICATION_ERROR：DuerOS与端通信异常。
    • INTERNAL_ERROR：其他DuerOS系统错误。
  • message: 错误信息，用于描述具体错误的可打印字符串。

示例

{
    "version": "2.0",
    "session": {
        "new": false,
        "sessionId": "1927e048-f8bf-4201-9c97-cf2fba5f992a",
        "attributes": {}
    },
    "context": {
        "System": {
            "application": {
                "applicationId":"personal_income_tax"
            }
        }
    },
    "request": {
        "type": "SessionEndedRequest",
        "requestId": "33c78c8f-22db-4d6a-bfd5-075d264377b7",
        "timestamp": "1501127440",
        "reason": "USER_INITIATED"
    }
}