# 技能请求格式

开发自定义技能时,主要的工作量在于:

  • 处理iFLYOS发送的不同类型的请求
  • 在返回完整回复前选择性地发送一些信息给用户,比如告诉用户系统正在处理中
  • 对用户的请求返回合适的回复

# 请求校验

在你的技能服务接受请求之前,你应该先辨别这个请求是不是安全有效的。以避免终端设备被别人非法入侵后对你的技能发起非法请求。

  • 每一个iFLYOS发送的请求均包含一个application_ID,你需要检查这个ID是否和你的技能ID相同;
  • 所有发送给技能的请求Header都包含Signature字段(校验步骤

当请求不符合以上两点,你应该返回HTTP CODE: 400.

# HTTP头

POST / HTTP/1.1
Content-Type : application/json;charset=UTF-8
Host : your.application.endpoint
Content-Length :
Accept : application/json
Accept-Charset : utf-8
Signature: xxxxxxxxxxxxxxx

# Body示例

{
  "version": "1.1",
  "session": {
    "new": true,
    "sessionId": "f78b7d68...",
    "attributes": {
      "key": "String value"
    }
  },
  "context": {
    "System": {
      "device": {
        "deviceId": "f78b7d68...",
        "supportedInterfaces": {
          "AudioPlayer": {},
          "Display":{}
        },
        "location":{
          "lng": float,
          "lat": float
        }
      },
      "application": {
        "applicationId": "f78b7d68..."
      },
      "user": {
        "userId": "f78b7d68...",
        "accessToken": "23bf653f..."
      }
    },
    "AudioPlayer": {
      "playerActivity": "PLAYING",
      "token": "audioplayer-token",
      "offsetInMilliseconds": 0
    }
  },
  "request": {}
}

正文参数说明

所有请求都包含顶层的versionsessioncontextrequest对象。

参数 描述 类型 必须出现
version 请求的版本, 其值定义为: "1.0 " String
session 用户的会话信息,仅包含在标准请求中。查看详细 Object
context 设备端状态。查看详细 Object
request 经过iFLYOS解析的用户请求。 Object

# session参数说明

session表示用户会话信息,一次session过程从用户调起技能到结束,表示用户与技能的一次会话。会话结束方式:技能返回结束,用户明确结束,或用户输入错误导致结束。

参数 描述 类型 必须出现
new 一个布尔值, 指示这是否为新会话。新会话返回true,已有会话的返回false 。 boolean
sessionId 活动会话的唯一标识符。sessionId 对于用户和会话的多个后续请求是一致的。如果用户的会话结束, 则为同一用户的后续请求提供一个新的唯一 sessionId 值。 String
attributes 用于保存上下文信息,由开发者自定义上传。对于新会话已从新设置为 true 的新会话, 属性映射为空。
拦截器可在response中的sessionAttributes中设置属性,在同一会话的下一次请求中在此字段中回传。
map

# context参数说明

在向服务发送请求时, context对象提供了有关 IVS 服务和设备当前状态的信息。对于在会话上下文 (CanFulfillIntentRequest、LaunchRequest 和 IntentRequest) 中发送的请求, context对象将复制会话对象中可用的用户和应用程序信息。

参数 描述 类型 必须出现
System 有关ivs与技能交互的设备的信息 Object
System.application 技能信息。包含:
- applicationId
Object
System.device 设备信息。包含:
- deviceId:设备唯一标识符。
- suportedInterfaces:设备支持的接口列表。取值:AudioPlayer: {}
Object
System.user 用户信息。包含:
- userId:提出请求的用户的唯一标识符。不超过255个字符。这个userId是在用户启用技能时自动生成的。禁用和重新启用技能会说呢过程新的标识符。
- accessToken:第三方(拦截器服务)的授权token。
Object
AudioPlayer 音频播放器当前状态 Object
AudioPlayer.token 音频资源的标识符。该字段只发送给最近一次播放音频的技能方。 String
AudioPlayer.
offsetInMilliseconds
播放进度。该字段只发送给最近一次播放音频的技能方。 Long
AudioPlayer.
playerActivity
音频播放器状态。取值 : IDLE,PAUSED,PLAYING,BUFFER_UNDERRUN,FINISHED,STOPPED String

# request参数说明

request中包含经过iFLYOS解析后的用户请求。他们分为:

  • 标准请求

    • LaunchRequest: 用户通过入口词“打开{技能名称}”进入你的技能时,你将会收到这个请求。
    • TextRequest: 在你的技能中,用户的语音请求未经过iFLYOS解析直接请求你的服务器时,你将会收到这个请求。
    • IntentRequest: 用户的语音请求经过iFLYOS解析后请求你的服务器时,你将会收到这个请求。
    • SessionEndedRequest: 用户主动退出技能结束会话时,你将会收到这个请求。
  • 音频请求

    • AudioPlayer: 当你的技能使用设备的音频播放能力时,音频播放状态会通过这个请求发送给你。
    • PlaybackController: 当你的技能使用设备的音频播放能力时,用户在设备的GUI界面或物理按键上进行音频控制操作时,你将会收到这个请求。