Studio WebSocket API

asyncapi: 3.0.0
id: urn:studio:websocket:v1
info:
  title: Studio WebSocket API
  version: v1
  description: |
    本文件描述客户端与 Studio WebSocket 服务之间的异步消息：
    - 客户端发送鉴权、心跳、订阅、取消订阅请求。
    - Studio 返回请求响应，并在订阅命中或设备事件发生时主动推送消息。
    - 本契约覆盖设备、Trait 和对象事件订阅，不覆盖 SubscribeEventRequest、UnsubscribeEventRequest 等独立告警事件订阅。
    - Studio 局域网 Studio 环境如未在握手阶段携带 Token，可在连接建立后首包发送 `AuthRequest`。

    视角说明：本 AsyncAPI 描述客户端应用需要实现的接入行为；`send` 表示客户端发送到 Studio，`receive` 表示客户端从 Studio 接收。
defaultContentType: application/json

servers:
  lanStudio:
    host: '{localStudioEndpoint}'
    protocol: wss
    pathname: /open/ws
    description: 局域网 Studio WebSocket 服务，仅用于本地连接；地址由部署配置或服务发现结果提供，不得用于生产或云端连接。
    variables:
      localStudioEndpoint:
        default: studio.local
        description: Studio 实际主机地址以及环境需要的端口，不应在客户端硬编码固定 IP 或端口。

channels:
  studioWebSocket:
    address: null
    title: Studio WebSocket channel
    description: |
      单连接双向 JSON 文本消息通道。

      新接入统一使用 `studio-id`；服务端当前兼容 `X-Studio-Id`、`Studio-Id`、`studioId` 等历史名称。
      Studio 局域网 Studio 环境可使用握手 Header 认证；如未在握手 Header 携带 Authorization，客户端必须在连接建立后 7 秒内发送 `AuthRequest`。
      Studio 局域网 Studio 环境使用 `AuthRequest` 时，鉴权完成前只允许发送 `AuthRequest`；鉴权成功后再发送心跳、订阅、取消订阅等业务消息。
      客户端应周期性发送 `ping` 或其他业务消息保持连接活跃，发送间隔不应超过 30 秒；超过 30 秒无任何消息时，链路中的网关或代理可能主动断开 WebSocket 连接。
      使用 API AccessToken 且配置了访问范围时，设备/Trait 订阅需要授权 `POST /api/v1/devices/trait/read`，也可授权 `*`。对象事件订阅属于认证连接可用的隐藏默认能力，不要求单独配置 scope。
      WebSocket 建立后应立即启动消息接收和临时缓冲，再完成鉴权、恢复订阅和快照校准，避免遗漏认证完成后默认推送的设备增删事件。
    messages:
      AuthRequest:
        $ref: '#/components/messages/AuthRequest'
      AuthResponse:
        $ref: '#/components/messages/AuthResponse'
      PingRequest:
        $ref: '#/components/messages/PingRequest'
      PongResponse:
        $ref: '#/components/messages/PongResponse'
      SubscribeAllRequest:
        $ref: '#/components/messages/SubscribeAllRequest'
      SubscribeAllResponse:
        $ref: '#/components/messages/SubscribeAllResponse'
      UnsubscribeAllRequest:
        $ref: '#/components/messages/UnsubscribeAllRequest'
      UnsubscribeAllResponse:
        $ref: '#/components/messages/UnsubscribeAllResponse'
      SubscribeTraitValueRequest:
        $ref: '#/components/messages/SubscribeTraitValueRequest'
      SubscribeTraitValueResponse:
        $ref: '#/components/messages/SubscribeTraitValueResponse'
      UnsubscribeTraitValueRequest:
        $ref: '#/components/messages/UnsubscribeTraitValueRequest'
      UnsubscribeTraitValueResponse:
        $ref: '#/components/messages/UnsubscribeTraitValueResponse'
      SubscribeObjectEventRequest:
        $ref: '#/components/messages/SubscribeObjectEventRequest'
      SubscribeObjectEventResponse:
        $ref: '#/components/messages/SubscribeObjectEventResponse'
      UnsubscribeObjectEventRequest:
        $ref: '#/components/messages/UnsubscribeObjectEventRequest'
      UnsubscribeObjectEventResponse:
        $ref: '#/components/messages/UnsubscribeObjectEventResponse'
      TraitValueUpdate:
        $ref: '#/components/messages/TraitValueUpdate'
      ObjectEvent:
        $ref: '#/components/messages/ObjectEvent'
      ErrorMessage:
        $ref: '#/components/messages/ErrorMessage'

operations:
  sendAuthRequest:
    action: send
    description: 仅 Studio 自身域名地址和局域网 Studio 环境使用；生产或云端环境不使用 AuthRequest。
    channel:
      $ref: '#/channels/studioWebSocket'
    messages:
      - $ref: '#/channels/studioWebSocket/messages/AuthRequest'
  receiveAuthResponse:
    action: receive
    channel:
      $ref: '#/channels/studioWebSocket'
    messages:
      - $ref: '#/channels/studioWebSocket/messages/AuthResponse'
      - $ref: '#/channels/studioWebSocket/messages/ErrorMessage'
  sendPing:
    action: send
    channel:
      $ref: '#/channels/studioWebSocket'
    messages:
      - $ref: '#/channels/studioWebSocket/messages/PingRequest'
  receivePong:
    action: receive
    channel:
      $ref: '#/channels/studioWebSocket'
    messages:
      - $ref: '#/channels/studioWebSocket/messages/PongResponse'
      - $ref: '#/channels/studioWebSocket/messages/ErrorMessage'
  sendSubscriptionCommand:
    action: send
    channel:
      $ref: '#/channels/studioWebSocket'
    messages:
      - $ref: '#/channels/studioWebSocket/messages/SubscribeAllRequest'
      - $ref: '#/channels/studioWebSocket/messages/UnsubscribeAllRequest'
      - $ref: '#/channels/studioWebSocket/messages/SubscribeTraitValueRequest'
      - $ref: '#/channels/studioWebSocket/messages/UnsubscribeTraitValueRequest'
      - $ref: '#/channels/studioWebSocket/messages/SubscribeObjectEventRequest'
      - $ref: '#/channels/studioWebSocket/messages/UnsubscribeObjectEventRequest'
  receiveSubscriptionCommandResponse:
    action: receive
    description: |
      订阅或取消订阅失败时，服务端可能返回 ErrorMessage，也可能返回与请求对应的业务响应类型且 code 非 0。
      调用端应按 msgId 关联请求，并对所有响应统一判断 code，不应只等待固定响应 type。
    channel:
      $ref: '#/channels/studioWebSocket'
    messages:
      - $ref: '#/channels/studioWebSocket/messages/SubscribeAllResponse'
      - $ref: '#/channels/studioWebSocket/messages/UnsubscribeAllResponse'
      - $ref: '#/channels/studioWebSocket/messages/SubscribeTraitValueResponse'
      - $ref: '#/channels/studioWebSocket/messages/UnsubscribeTraitValueResponse'
      - $ref: '#/channels/studioWebSocket/messages/SubscribeObjectEventResponse'
      - $ref: '#/channels/studioWebSocket/messages/UnsubscribeObjectEventResponse'
      - $ref: '#/channels/studioWebSocket/messages/ErrorMessage'
  receivePushMessage:
    action: receive
    channel:
      $ref: '#/channels/studioWebSocket'
    messages:
      - $ref: '#/channels/studioWebSocket/messages/TraitValueUpdate'
      - $ref: '#/channels/studioWebSocket/messages/ObjectEvent'
      - $ref: '#/channels/studioWebSocket/messages/ErrorMessage'

components:
  messages:
    AuthRequest:
      name: AuthRequest
      title: WebSocket 鉴权请求
      summary: Studio 自身域名地址和局域网 Studio 环境的首包认证方式；生产或云端环境不使用。
      payload:
        $ref: '#/components/schemas/AuthRequestMessage'
      examples:
        - name: bearerToken
          payload:
            type: AuthRequest
            version: v1
            msgId: '10001'
            data:
              authType: token
              token: '<accessToken>'
              deviceUniqueId: '<deviceUniqueId>'
              clientId: '<clientId>'
    AuthResponse:
      name: AuthResponse
      title: WebSocket 鉴权响应
      correlationId:
        location: $message.payload#/msgId
      payload:
        $ref: '#/components/schemas/AuthResponseMessage'
      examples:
        - name: success
          payload:
            type: AuthResponse
            version: v1
            msgId: '10001'
            data: ''
            code: 0
            message: Authentication successful. Welcome <username>
    PingRequest:
      name: ping
      title: 心跳请求
      payload:
        $ref: '#/components/schemas/PingRequestMessage'
      examples:
        - name: ping
          payload:
            type: ping
            version: v1
            msgId: '10002'
            data: null
    PongResponse:
      name: pong
      title: 心跳响应
      correlationId:
        location: $message.payload#/msgId
      payload:
        $ref: '#/components/schemas/PongResponseMessage'
      examples:
        - name: pong
          payload:
            type: pong
            version: v1
            msgId: '10002'
            data: pong
            code: 0
            message: success
    SubscribeAllRequest:
      name: SubscribeAllRequest
      title: 全量/设备级订阅
      payload:
        $ref: '#/components/schemas/SubscribeAllRequestMessage'
      examples:
        - name: allDevices
          payload:
            type: SubscribeAllRequest
            version: v1
            msgId: '1751609244328'
            data: null
        - name: allDevicesWithEmptyArray
          payload:
            type: SubscribeAllRequest
            version: v1
            msgId: '1751609244329'
            data: []
        - name: specifiedDevices
          payload:
            type: SubscribeAllRequest
            version: v1
            msgId: '1751609244328'
            data:
              - deviceId
    SubscribeAllResponse:
      name: SubscribeAllResponse
      title: 全量/设备级订阅响应
      correlationId:
        location: $message.payload#/msgId
      payload:
        $ref: '#/components/schemas/SubscribeAllResponseMessage'
    UnsubscribeAllRequest:
      name: UnsubscribeAllRequest
      title: 取消全量/设备级订阅
      description: |
        清理全部或指定设备的数据订阅，并同时清理当前会话的 Trait 订阅。
        不清理独立事件订阅、精确对象事件订阅，也不关闭认证连接默认接收的 DEVICE_ADDED、DEVICE_REMOVED。
      payload:
        $ref: '#/components/schemas/UnsubscribeAllRequestMessage'
    UnsubscribeAllResponse:
      name: UnsubscribeAllResponse
      title: 取消全量/设备级订阅响应
      correlationId:
        location: $message.payload#/msgId
      payload:
        $ref: '#/components/schemas/UnsubscribeAllResponseMessage'
    SubscribeTraitValueRequest:
      name: SubscribeTraitValueRequest
      title: 订阅指定 Trait 功能值
      payload:
        $ref: '#/components/schemas/SubscribeTraitValueRequestMessage'
      examples:
        - name: subscribeTrait
          payload:
            type: SubscribeTraitValueRequest
            version: v1
            msgId: get_devices_1751609244328
            data:
              - deviceId: '57190441014857'
                endpointId: 3
                functionCode: MediaPlayback
                traitCodes:
                  - TargetPlaybackState
    SubscribeTraitValueResponse:
      name: SubscribeTraitValueResponse
      title: 订阅指定 Trait 功能值响应
      correlationId:
        location: $message.payload#/msgId
      payload:
        $ref: '#/components/schemas/SubscribeTraitValueResponseMessage'
    UnsubscribeTraitValueRequest:
      name: UnsubscribeTraitValueRequest
      title: 取消订阅指定 Trait 功能值
      payload:
        $ref: '#/components/schemas/UnsubscribeTraitValueRequestMessage'
    UnsubscribeTraitValueResponse:
      name: UnsubscribeTraitValueResponse
      title: 取消订阅指定 Trait 功能值响应
      correlationId:
        location: $message.payload#/msgId
      payload:
        $ref: '#/components/schemas/UnsubscribeTraitValueResponseMessage'
    SubscribeObjectEventRequest:
      name: SubscribeObjectEventRequest
      title: 订阅空间、设备空间关系和自动化对象事件
      summary: 按当前 WebSocket 会话增量增加对象事件订阅；重复订阅幂等。
      description: |
        objectIds 不传、为 null 或空数组时订阅对应 eventTypes 下当前可访问的全部对象；非空时订阅指定对象。
        后续订阅请求与已有规则合并，不会覆盖之前的指定对象规则。订阅全部对象会覆盖同一事件类型已有的 ID 列表。
        App 可使用全部对象订阅维护完整列表；带屏设备和第三方服务通常按业务范围订阅指定对象。
      payload:
        $ref: '#/components/schemas/SubscribeObjectEventRequestMessage'
      examples:
        - name: subscribeAllPreciseObjectEvents
          payload:
            type: SubscribeObjectEventRequest
            version: v1
            msgId: object-subscribe-1
            data:
              - eventTypes:
                  - SPACE_ADDED
                  - SPACE_REMOVED
                  - SPACE_UPDATED
                  - AUTOMATION_ADDED
                  - AUTOMATION_REMOVED
                  - AUTOMATION_UPDATED
                  - AUTOMATION_SPACE_UPDATED
                  - DEVICE_SPACE_UPDATED
                objectIds: []
        - name: subscribeSelectedObjects
          payload:
            type: SubscribeObjectEventRequest
            version: v1
            msgId: object-subscribe-2
            data:
              - eventTypes:
                  - DEVICE_SPACE_UPDATED
                objectIds:
                  - device-1
                  - device-2
              - eventTypes:
                  - AUTOMATION_REMOVED
                  - AUTOMATION_UPDATED
                  - AUTOMATION_SPACE_UPDATED
                objectIds:
                  - automation-1
    SubscribeObjectEventResponse:
      name: SubscribeObjectEventResponse
      title: 对象事件订阅响应
      correlationId:
        location: $message.payload#/msgId
      payload:
        $ref: '#/components/schemas/SubscribeObjectEventResponseMessage'
    UnsubscribeObjectEventRequest:
      name: UnsubscribeObjectEventRequest
      title: 取消空间、设备空间关系和自动化对象事件订阅
      summary: 按当前 WebSocket 会话移除指定对象规则或清空指定事件类型。
      description: |
        objectIds 非空时只移除指定对象；不传、为 null 或空数组时清空对应 eventTypes 的全部对象规则。
        全量订阅不支持排除部分对象；要从全量切换为指定对象，应先清空事件类型，再发送新的指定对象订阅。
      payload:
        $ref: '#/components/schemas/UnsubscribeObjectEventRequestMessage'
      examples:
        - name: unsubscribeSelectedObject
          payload:
            type: UnsubscribeObjectEventRequest
            version: v1
            msgId: object-unsubscribe-1
            data:
              - eventTypes:
                  - AUTOMATION_UPDATED
                objectIds:
                  - automation-1
        - name: clearEventType
          payload:
            type: UnsubscribeObjectEventRequest
            version: v1
            msgId: object-unsubscribe-2
            data:
              - eventTypes:
                  - AUTOMATION_UPDATED
                objectIds: []
    UnsubscribeObjectEventResponse:
      name: UnsubscribeObjectEventResponse
      title: 取消对象事件订阅响应
      correlationId:
        location: $message.payload#/msgId
      payload:
        $ref: '#/components/schemas/UnsubscribeObjectEventResponseMessage'
    TraitValueUpdate:
      name: TraitValueUpdate
      title: Trait 功能值变化推送
      payload:
        $ref: '#/components/schemas/PushTraitValueUpdateMessageV1'
      examples:
        - name: traitValueUpdate
          payload:
            type: TraitValueUpdate
            version: v1
            msgId: '1754469720110'
            data:
              - deviceId: '57190441014857'
                endpointId: 3
                functionCode: MediaPlayback
                traitCode: TargetPlaybackState
                value: '0'
                time: 1754469720110
            code: 0
            message: ''
        - name: deviceNameUpdated
          payload:
            type: TraitValueUpdate
            version: v1
            msgId: '1789113600000'
            data:
              - deviceId: device-1
                endpointId: 0
                functionCode: EndpointLabel
                traitCode: EndpointName
                value: 客厅灯
                time: 1789113600000
            code: 0
            message: ''
    ObjectEvent:
      name: objectEvent
      title: 对象事件推送
      summary: 设备增删默认推送；空间、自动化和空间关联变化按精确对象订阅投递。
      description: |
        DEVICE_ADDED、DEVICE_REMOVED 在认证连接建立后默认推送。
        
        SPACE_*、AUTOMATION_*、DEVICE_SPACE_UPDATED 仅投递给命中 eventType、objectId 和当前权限的 SubscribeObjectEventRequest 会话。
        
        DEVICE_ENDPOINT_*、DEVICE_TRAIT_PARAMETER_UPDATE 继续跟随现有设备数据订阅。

        独立场景通过 /scenes 管理，变化通知沿用 AUTOMATION_* 事件族；对象分类以 /automations 和 /scenes 查询结果为准。数量变化不提供独立事件。

        场景是自动化内部的 manualTriggers，不提供独立场景事件；数量变化不提供独立事件。

        协议不提供全局唯一的事件 ID；推送 msgId 只用于链路追踪，调用端应按对象状态幂等处理，不应仅按 objectId、eventType、time 去重。
      payload:
        $ref: '#/components/schemas/PushObjectEventMessageV1'
      examples:
        - name: deviceAdded
          payload:
            type: objectEvent
            version: v1
            msgId: '2'
            data:
              eventType: DEVICE_ADDED
              objectId: 14d3b91
              time: 1754469720110
              data:
                deviceId: 14d3b91
                name: ''
                deviceTypesList:
                  - Light
                endpointIds:
                  - 0
                  - 2
                  - 3
                time: 1754469720110
            code: 0
            message: success
        - name: deviceSpaceUpdated
          payload:
            type: objectEvent
            version: v1
            msgId: object-event-1
            data:
              eventType: DEVICE_SPACE_UPDATED
              objectId: device-1
              time: 1789113600000
              data:
                deviceId: device-1
                oldSpaceId: space-1
                space:
                  spaceId: space-2
                  name: 卧室
                  spatialMarking: room
                  parentSpaceId: home-1
            code: 0
            message: success
        - name: automationUpdated
          payload:
            type: objectEvent
            version: v1
            msgId: object-event-2
            data:
              eventType: AUTOMATION_UPDATED
              objectId: automation-1
              time: 1789113600000
              data:
                automationId: automation-1
                definitionType: WHEN_IF_THEN
                name: 回家模式
                enabled: true
                createTime: 1789000000000
            code: 0
            message: success
        - name: automationSpaceUnassigned
          payload:
            type: objectEvent
            version: v1
            msgId: object-event-3
            data:
              eventType: AUTOMATION_SPACE_UPDATED
              objectId: automation-1
              time: 1789113600000
              data:
                automationId: automation-1
                oldSpaceId: space-2
                space: null
            code: 0
            message: success
    ErrorMessage:
      name: ErrorMessage
      title: 错误响应
      correlationId:
        location: $message.payload#/msgId
      payload:
        $ref: '#/components/schemas/ErrorMessageV1'
      examples:
        - name: missingMsgId
          payload:
            type: ErrorMessage
            version: v1
            msgId: ''
            data: null
            code: 400
            message: Missing msgId

  schemas:
    MessageType:
      type: string
      description: 本文协议及共享推送 Schema 使用的消息类型；实际可用消息以对应 channel 和 operation 为准。
      enum:
        - AuthRequest
        - AuthResponse
        - ping
        - pong
        - SubscribeAllRequest
        - SubscribeAllResponse
        - UnsubscribeAllRequest
        - UnsubscribeAllResponse
        - SubscribeTraitValueRequest
        - SubscribeTraitValueResponse
        - UnsubscribeTraitValueRequest
        - UnsubscribeTraitValueResponse
        - SubscribeObjectEventRequest
        - SubscribeObjectEventResponse
        - UnsubscribeObjectEventRequest
        - UnsubscribeObjectEventResponse
        - TraitValueUpdate
        - objectEvent
        - AlarmEvent
        - ErrorMessage
    PushAlarmEventMessageV1:
      description: 共享的原始告警推送 Schema。仅定义正文，不为本文现有 WebSocket channel 新增告警订阅操作。HTTP 推送复用此 Schema，不使用 App 通知栏 payload。
      allOf:
        - $ref: '#/components/schemas/BasePushMessage'
        - type: object
          properties:
            type:
              type: string
              enum: [AlarmEvent]
            data:
              $ref: '#/components/schemas/AlarmEventDataV1'
    AlarmEventDataV1:
      type: object
      required: [uuid, deviceName, deviceId, devicePointName, alarmClass, alarmRuleName, alarmText, alarmValue, sourceState, alarmTime, localized]
      properties:
        uuid: {type: string}
        deviceName: {type: string}
        deviceId: {type: string}
        devicePointName: {type: string}
        alarmClass: {type: string}
        alarmRuleName: {type: string}
        alarmText: {type: string}
        alarmValue: {type: string}
        sourceState: {type: string}
        alarmTime: {type: integer, format: int64, description: Unix 毫秒时间戳}
        localized:
          type: object
          minProperties: 1
          description: 按语言标签提供文本；部分语言构建失败时可缺失，顶层文本使用系统默认语言或可用回退语言。
          additionalProperties:
            type: object
            required: [devicePointName, alarmText, alarmValue, sourceStateText]
            properties:
              devicePointName: {type: string}
              alarmText: {type: string}
              alarmValue: {type: string}
              sourceStateText: {type: string}
    MsgId:
      type: string
      description: 请求使用的非空标识，应至少在当前连接尚未完成的请求中保持唯一；正常响应使用相同 msgId 关联，服务端推送的 msgId 仅用于链路追踪，不等同于订阅请求 msgId，也不保证全局唯一。
      minLength: 1
      maxLength: 64
    ErrorMsgId:
      type: string
      description: 能关联原请求时返回请求 msgId；服务端无法关联原请求时可能返回 UNKNOWN 或空字符串。
      minLength: 0
      maxLength: 64
    Version:
      type: string
      enum:
        - v1
    BaseRequest:
      type: object
      required:
        - type
        - version
        - msgId
      properties:
        type:
          $ref: '#/components/schemas/MessageType'
        version:
          $ref: '#/components/schemas/Version'
        msgId:
          $ref: '#/components/schemas/MsgId'
        data:
          description: 业务参数。
    BaseResponse:
      type: object
      required:
        - type
        - version
        - msgId
        - code
        - message
      properties:
        type:
          $ref: '#/components/schemas/MessageType'
        version:
          $ref: '#/components/schemas/Version'
        msgId:
          $ref: '#/components/schemas/MsgId'
        data:
          description: 响应数据。无数据时通常为空字符串或 null。
        code:
          type: integer
          format: int32
          description: 处理结果码，0 表示成功，非 0 表示失败。
        message:
          type:
            - string
            - 'null'
          description: 处理结果描述。
    BasePushMessage:
      type: object
      required:
        - type
        - version
        - msgId
        - data
        - code
        - message
      properties:
        type:
          $ref: '#/components/schemas/MessageType'
        version:
          $ref: '#/components/schemas/Version'
        msgId:
          $ref: '#/components/schemas/MsgId'
        data:
          description: 推送业务数据。
        code:
          type: integer
          format: int32
          description: 处理结果码，0 表示成功，非 0 表示失败。
        message:
          type:
            - string
            - 'null'
          description: 处理结果描述。
    AuthRequestMessage:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          required:
            - data
          properties:
            type:
              type: string
              enum:
                - AuthRequest
            data:
              $ref: '#/components/schemas/AuthRequestData'
    AuthRequestData:
      type: object
      required:
        - token
      properties:
        authType:
          type: string
          description: 鉴权方式。请传入 token。
          enum:
            - token
          default: token
        token:
          type: string
          description: "请使用格式：`Bearer <Token>`，其中 `<Token>` 为 Aqara Studio 获取的原始 Token。切勿将此 Token 记录或暴露于日志。"
    CommonEmptyResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          required:
            - data
          properties:
            data:
              type:
                - string
                - 'null'
              default: ''
    AuthResponseMessage:
      allOf:
        - $ref: '#/components/schemas/CommonEmptyResponse'
        - type: object
          properties:
            type:
              type: string
              enum:
                - AuthResponse
    SubscribeAllResponseMessage:
      allOf:
        - $ref: '#/components/schemas/CommonEmptyResponse'
        - type: object
          properties:
            type:
              type: string
              enum:
                - SubscribeAllResponse
    UnsubscribeAllResponseMessage:
      allOf:
        - $ref: '#/components/schemas/CommonEmptyResponse'
        - type: object
          properties:
            type:
              type: string
              enum:
                - UnsubscribeAllResponse
    SubscribeTraitValueResponseMessage:
      allOf:
        - $ref: '#/components/schemas/CommonEmptyResponse'
        - type: object
          properties:
            type:
              type: string
              enum:
                - SubscribeTraitValueResponse
    UnsubscribeTraitValueResponseMessage:
      allOf:
        - $ref: '#/components/schemas/CommonEmptyResponse'
        - type: object
          properties:
            type:
              type: string
              enum:
                - UnsubscribeTraitValueResponse
    SubscribeObjectEventResponseMessage:
      allOf:
        - $ref: '#/components/schemas/CommonEmptyResponse'
        - type: object
          properties:
            type:
              type: string
              enum:
                - SubscribeObjectEventResponse
    UnsubscribeObjectEventResponseMessage:
      allOf:
        - $ref: '#/components/schemas/CommonEmptyResponse'
        - type: object
          properties:
            type:
              type: string
              enum:
                - UnsubscribeObjectEventResponse
    PingRequestMessage:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            type:
              type: string
              enum:
                - ping
            data:
              type:
                - string
                - 'null'
              default: null
    PongResponseMessage:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          required:
            - data
          properties:
            type:
              type: string
              enum:
                - pong
            data:
              type: string
              enum:
                - pong
    SubscribeAllRequestMessage:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            type:
              type: string
              enum:
                - SubscribeAllRequest
            data:
              type:
                - array
                - 'null'
              default: null
              description: |
                设备 ID 列表。为 null、省略或空数组时表示订阅当前权限范围内全部设备数据，并清理此前的设备级订阅。
                data 不为空时会取消“订阅所有设备”状态并追加这些设备级订阅，但不会自动清理此前已追加的其他设备级订阅。
                若需要缩小或替换设备级订阅范围，应先用 UnsubscribeAllRequest 取消不再需要的设备。
                若需要清理当前连接全部设备数据和 Trait 订阅，应发送 data 为空数组或不传的 UnsubscribeAllRequest；该请求不清理独立事件或对象事件订阅。
                若当前账号或 Token 权限范围内没有可访问设备，服务端可能返回 code=0 但不会产生后续推送。
                同一连接内，SubscribeAllRequest 会覆盖并清理此前通过 SubscribeTraitValueRequest 建立的 Trait 订阅。
                若需从全部设备或指定设备订阅切换回仅 Trait 维度订阅，应先发送 UnsubscribeAllRequest 清理全量/设备级订阅。
              items:
                type: string
    UnsubscribeAllRequestMessage:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            type:
              type: string
              enum:
                - UnsubscribeAllRequest
            data:
              type:
                - array
                - 'null'
              default: null
              description: |
                设备 ID 列表。为空或 null 时表示取消全部设备数据和 Trait 订阅。
                若当前为全部设备订阅，按特定设备取消订阅不会生效，需传空值取消全部设备数据订阅。
                同一连接内，UnsubscribeAllRequest 会同时清理此前通过 SubscribeTraitValueRequest 建立的 Trait 订阅。
                按特定设备取消订阅只取消设备级订阅，不等同于关闭当前连接的全部推送。
                本请求不清理 SubscribeEventRequest 或 SubscribeObjectEventRequest 建立的规则，也不关闭默认 DEVICE_ADDED、DEVICE_REMOVED 推送。
              items:
                type: string
    TraitSubscriptionItem:
      type: object
      required:
        - deviceId
        - endpointId
        - functionCode
        - traitCodes
      properties:
        deviceId:
          type: string
          description: 设备 ID。
        endpointId:
          type: integer
          format: int32
          description: 端点 ID。
        functionCode:
          type: string
          description: 功能代码。
        traitCodes:
          type: array
          description: Trait 功能点代码列表。建议传非空数组；为空数组时不会创建或取消具体 Trait 订阅，但当前实现仍可能返回成功响应。
          items:
            type: string
    SubscribeTraitValueRequestMessage:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          required:
            - data
          properties:
            type:
              type: string
              enum:
                - SubscribeTraitValueRequest
            data:
              type: array
              description: |
                需要订阅的 Trait 列表。建议传非空数组；省略 data 会解析失败。
                当前实现对空数组或 traitCodes 为空数组仍可能返回成功响应，但不会创建有效的 TraitValueUpdate 订阅。
              items:
                $ref: '#/components/schemas/TraitSubscriptionItem'
    UnsubscribeTraitValueRequestMessage:
      allOf

# --- truncated at 32 KB (47 KB total) ---
# Full source: https://artifacts.apis.io/aqara/asyncapi/data-export-api-zh.yaml