# 消息格式

所有技能适配器指令(无论是由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 指令的名称,如DiscoverAppliancesRequestDiscoverAppliancesResponse
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