# 消息格式
所有技能适配器指令(无论是由Smart Home Skill API发送到适配器还是由适配器发送回Smart Home Skill API)共享相同的基本结构。 技能适配器指令包含两个顶级对象:
- Header
- Payload
另外,两个方向上的技能适配器指令的大小限制都是128KB。字段名区分大小写。
# Header (Message Headers)
指令头具有一组在消息类型中相同的预期字段。 它们描述消息命名空间(namespace),指令名称(name),目标版本(payloadVersion)和唯一消息标识符(messageId)。 以下是典型的Message Header的JSON示例:
{
"header": {
"messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
"name": "DiscoverAppliancesRequest",
"namespace": "SmartHome.Discovery",
"payloadVersion": "2"
}
}
header必须包含以下属性:
参数 | 描述 |
---|---|
messageID | 单个请求或响应的唯一标识符。 这用于跟踪目的,技能适配器应该记录此信息,尽管它不应用于支持业务逻辑。 来自技能适配器的每条消息都必须填充此字段。 任何只包含数字字符及‘-’且长度短于128的字符串都是有效的,但是推荐使用随机数生成的UUID。 |
name | 指令的名称,如DiscoverAppliancesRequest或DiscoverAppliancesResponse |
namespace | 指令所在的命名空间。 目前的类别有: SmartHome.Discovery SmartHome.Control SmartHome.Query |
payloadVersion | 应用于Payload的API版本。 当前版本为2,该版本的payload格式在本文档中描述。 |
# Payload(Message Payload)
技能适配器指令的Payload取决于在Header中指定的指令的名称,并且Payload属性将根据请求中包含的指令而有所不同。 每个指令类型详细描述有效载荷内容。
以下部分描述不同类型的指令,其预期的Payload描述和示例。
任务 | 类别 | 指令名称 |
---|---|---|
发现已连接设备 | SmartHome.Discovery | DiscoverAppliancesRequest DiscoverAppliancesResponse |
控制连接设备:打开、关闭,更改设置等 | SmartHome.Control | DecrementColorTemperatureRequest DecrementColorTemperatureConfirmation DecrementPercentageRequest DecrementPercentageConfirmation DecrementBrightnessRequest DecrementBrightnessConfirmation IncrementColorTemperatureRequest IncrementColorTemperatureConfirmation IncrementPercentageRequest IncrementPercentageConfirmation IncrementTargetTemperatureRequest IncrementTargetTemperatureConfirmation IncrementBrightnessRequest IncrementBrightnessConfirmation SetColorRequest SetColorConfirmation SetColorTemperatureRequest SetColorTemperatureConfirmation SetPercentageRequest SetPercentageConfirmation SetBrightnessRequest SetBrightnessConfirmation SetTargetTemperatureRequest SetTargetTemperatureConfirmation SetThermostatModeRequest SetThermostatModeConfirmation TurnOnRequest TurnOnConfirmation TurnOffRequest TurnOffConfirmation SetVolumeRequest SetVolumeConfirmation IncrementVolumeRequest IncrementVolumeConfirmation DecrementVolumeRequest DecrementVolumeConfirmation MuteRequest MuteConfirmation UnmuteRequest UnmuteConfirmation SelectChannelRequest SelectChannelConfirmation |
查询连接设备的当前状态 | SmartHome.Query | GetTargetTemperatureRequest GetTargetTemperatureResponse GetTemperatureReadingRequest GetTemperatureReadingResponse |