# 技能请求格式
开发自定义技能时,主要的工作量在于:
- 处理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": {}
}
正文参数说明
所有请求都包含顶层的version、session、context和request对象。
参数 | 描述 | 类型 | 必须出现 |
---|---|---|---|
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界面或物理按键上进行音频控制操作时,你将会收到这个请求。