DuerOS发送给技能的请求

摘要

DuerOS通过HTTPS（调试环境可使用HTTP/1）协议发送post请求给技能，请求内容是json格式。

下面定义了DuerOS发给技能的请求格式。

请求消息样例

{ 
    "version": "2.0",
    "session": {
        "new": boolean,
        "sessionId": "{{STRING}}",
        "attributes": {
            "{{STRING}}": "{{STRING}}"
        }
    },
    "context": {
        "System": {
            "user": {
                "userId": "{{STRING}}",
                "accessToken": "{{STRING}}",
            },
            "application": {
                "applicationId": "{{STRING}}"
            },
            "device": {
                "deviceId": "{{STRING}}",
                "supportedInterfaces": {
                    "VoiceInput": {},
                    "VoiceOutput": {},
                    "AudioPlayer": {},
                    "VideoPlayer": {
                        "preferedVideoCodec": [
                            "{{ENUM}}"
                        ],
                        "preferedAudioCodec": [
                            "{{ENUM}}"
                        ],
                        "preferedBitrate": "{{ENUM}}",
                        "preferedWidth": {{INT32}},
                        "preferedHeight": {{INT32}},
                    },
                    "Display": {}
                }
            }
        },
        "AudioPlayer": {
            "token": "{{STRING}}",
            "offsetInMilliSeconds": {{INT32}},
            "playerActivity": "{{STRING}}"
        },
        "VideoPlayer": {
            "token": "{{STRING}}",
            "error": {
                "type": "{{STRING}}",
                "message": "{{STRING}}"
            },
            "offsetInMilliseconds": {{INT32}},
            "playerActivity": "{{STRING}}"
        }
    },
    "request": {}
}

请求参数说明

• version
  • 协议版本号，当前为"2.0"。
• session
  • 用户会话信息，一次session过程是从开始用户调起技能到结束，表示用户与技能的一次会话。详见session参数说明。
• context
  • 设备端状态和参数。详见context参数说明。
• request
  • 经过DuerOS解析的用户请求，或者是技能相关的事件。详细的请求及事件请参考标准请求、AudioPlayer音乐播放事件、VideoPlayer视频播放事件和Form事件。

session参数说明

session表示用户会话信息，一次session过程是从开始用户调起技能到结束，表示用户与技能的一次会话。以下是一次完整的对话session交互过程。

参数说明

• new
  • 当用户向技能发起新的对话时，new为true，例如“打开个人所得税计算器”，该会话中后续的请求，new为false。
• sessionId
  • sessionId是一个唯一ID，用于标识一次对话。
• attributes
  • 技能用于记录本次对话的临时数据信息，当session.new为true时，attributes信息为空。用户可以在response信息中返回attributes，DuerOS会存储下来，并在本次对话的下一个request中发送给技能。

举例

用户 　：小度小度
技能 　： <被唤醒>
用户 　：打开个人所得税计算器
技能 　：欢迎光临
用户 　：帮我查一下个人所得税
技能 　：请问您的税前工资是多少呢
用户 　：我月薪8000元
技能 　：请问您所在城市是哪里呢
用户 　：我在北京
技能 　：需要缴纳个税960元
<会话结束>

context参数说明

设备端状态和参数。包括System即系统参数和AudioPlayer即音频播放状态。

• System
  • 系统信息。
• System.user
  • 用户信息。
• System.user.userId
  • 与用户登录帐号关联的一个用户id；每次enable skill产生一个新userId。
• System.user.accessToken
  • 用户用于做OAuth 2.0认证的access token。
• System.application
  • 技能信息。
• System.application.applicationId
  • applicationId是一个DBP平台生成的UUID，技能注册时生成，用于唯一标识一个技能；技能可用于验证该请求是否发给自己。
• System.device
  • 端上设备信息。
• System.device.deviceId
  • 经过转换的设备ID。同一设备对不同的技能展现的设备ID不同。
• System.device.deviceInfo
  • 设备信息。
• System.device.supportedInterfaces
  • 设备支持接口，包括：
    • VoiceInput
      • 语音输入。
    • VoiceOutput
      • 语音输出。
    • AudioPlayer
      • 音频播放。
    • Display
      • 使用展现模板在设备端展现图片。
• System.device.supportedInterfaces.VideoPlayer
  • 设备视频播放接口支持的播放参数，包括：
    • preferedVideoCodec: 支持的视频编码格式
      • H.264: H.264编码格式
      • H.265: H.265编码格式
      • MPEG-2: MPEG-2编码格式
      • VP8: VP8编码格式
      • VP9: VP9编码格式
    • preferedAudioCodec: 支持的音频编码格式
      • AAC: AAC编码格式
      • MP3: mp3编码格式
    • preferedBitrate: 支持的码率
      • 360P: 流畅360P
      • 480P: 高清480P
      • 720P: 超清720P
      • 1080P: 蓝光1080P
      • 4K: 蓝光4K
    • preferedWidth: 支持视频的宽
    • preferedHeight: 支持视频的高
• AudioPlayer
  • 音频端状态。
• AudioPlayer.token
  • 技能通过AudioPlayer.Play指令返回，用于在设备端唯一标识一个音频资源。
• AudioPlayer.offsetInMilliSeconds
  • 当前播放进度，单位毫秒。
• AudioPlayer.playActivity
  • 音频播放状态。取值如下：
    • PLAYING
      • 设备端正在播放audio item时所处的状态。PLAYING状态时可向服务器发送播放进度和audio item的元数据。
    • STOPPED
      • 以下几种情况会处于STOPPED状态：
        • 音频流出现问题导致播放失败。
        • 服务端下发STOP指令。
    • PAUSED
      • 当优先级更高的Channel进入活跃状态时（例如用户开始语音交互、闹铃响起），应当进入PAUSED状态。
    • BUFFER_UNDERRUN
      • 当设备端的流数据接收速度慢于播放速度时进入BUFER_UNDERRUN状态，直到缓冲完成才会恢复为PLAYING状态。
    • FINISHED
      • 在audio item播放完成时将转为FINISHED状态。即使设备端本地播放队列中有多个audio item待播放，在每一个audio item播放结束后也都需要向服务端发送PlaybackFinished事件，并且进入FINISHED状态。另外，设备启动后的初始状态也应当是FINISHED状态。
• VideoPlayer
  • 视频端状态。
• VideoPlayer.token
  • 技能通过VideoPlayer.Play指令返回，视频在播放过程中的唯一标识。
• VideoPlayer.error
  • 错误信息。
• VideoPlayer.error.type
  • 错误类型。
    • MEDIA_ERROR_UNKNOWN
      • 未知错误。
    • MEDIA_ERROR_INVALID_REQUEST
      • 设备端向视频stream的url地址发送请求，返回请求无效的情况，包括请求失败、请求地址未授权、请求地址被禁用、请求地址没找到等情况。
    • MEDIA_ERROR_SERVICE_UNAVAILABLE
      • 设备端无法连接视频stream的url地址。
    • MEDIA_ERROR_INTERNAL_SERVER_ERROR
      • 视频stream接受到请求，但未能正确处理。
    • MEDIA_ERROR_INTERNAL_DEVICE_ERROR
      • 设备端播放视频时内部出现错误。
• VideoPlayer.error.message
  • 错误描述。
• VideoPlayer.offsetInMilliseconds
  • 当前播放进度，单位毫秒。
• VideoPlayer.playActivity
  • 视频播放状态，包含以下状态。
    • PLAYING
      • 正在播放视频的状态为PLAYING。此时可以向技能发送播放进度和video item的元数据。
    • SCHEDULED_STOP
      • 处于PLAYING状态的视频播放到指定的停止点时，状态变为SCHEDULED_STOP。
    • STOPPED
      • 出现以下情况时，视频处于STOPPED状态。
        • 视频流出现问题导致播放失败。
        • 技能下发VideoPlayer.Stop指令。
        • 技能下发VideoPlayer.ClearQueue指令时，其中clearBehavior参数值为CLEAR_ALL。
        • 技能下发VideoPlayer.Play指令时，其中playBehavior参数值为REPLACE_ALL。
    • PAUSED
      • 当优先级更高的通道进入活跃状态时（例如用户开始语音交互、闹铃响起），视频会进入PAUSED状态。
    • BUFFER_UNDERRUN
      • 当设备端的流数据接收速度慢于播放速度时视频进入BUFER_UNDERRUN状态，直到缓冲完成才会恢复为PLAYING状态。
    • FINISHED
      • 在video item播放完成时状态变为FINISHED。