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": {}
}

请求参数说明

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。