Tuya.com
简体中文
English
注册
登录开发者平台
简体中文
English
注册
登录开发者平台
涂鸦开发者平台
search
根据文档目录筛选
涂鸦开发者平台智慧行业商用照明设备管控自定义群组管理

自定义群组管理

更新时间：2021-10-15 07:03:54下载pdf

本文介绍自定义群组管理相关 API。

API 列表

请求方式 API 描述
GET /v1.0/illumination/group/package/create/devices 可加入群组的设备列表
POST /v1.0/illumination/group/package 创建自定义群组
GET /v1.0/illumination/group/package/{groupPackageId}/devices 获取支持群组修改的设备
PUT /v1.0/illumination/group/package 修改自定义群组
DELETE /v1.0/illumination/group/package/{groupPackageId} 删除自定义群组
GET /v1.0/illumination/group/package 获取空间下自定义群组列表
GET /v1.0/illumination/project/group/package 获取项目下自定义群组列表
GET /v1.0/illumination/group/package/{groupPackageId} 单个自定义群组详情
GET /v1.0/illumination/group/package/devices 获取群组下设备列表
POST /v1.0/illumination/group/package/control 群组控制

可加入群组设备的列表

功能描述

创建群组前支持通过调用本 API 获取支持加入群组的设备列表。

接口地址

GET /v1.0/illumination/group/package/create/devices

请求参数

参数名 类型 参数类型 说明 是否必需
roomId String body 房间 ID true
deviceSaasId String body 设备商照唯一ID false

返回参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回十三位时间戳
result Object 返回结果

result参数说明

{
  "deviceSaasIds": "String[] //设备saasIds"
}

请求示例

{
  "deviceSaasId": "设备商照唯一ID",
  "roomId": "房间ID"
}

响应示例

{
  "deviceSaasIds": "设备saasIds"
}

创建自定义群组

功能描述

创建自定义群组。

接口地址

POST /v1.0/illumination/group/package

请求参数

参数名 类型 参数类型 说明 是否必需
roomId String body 房间 ID true
name String body 自定义群组名称 true
topCategory String body 一级品类 false
deviceSaasIds String[] body 设备saasId false

返回参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回十三位时间戳
result Object 返回结果

result参数说明

{
  "groupPackageId": "String //自定义群组ID",
  "taskId": "String //设备状态数量，如果返回null，不用展示耗时操作，直接任务完成",
  "expiredSeconds": "long //任务过期剩余秒数，如果返回null，不用展示耗时操作，直接任务完成",
  "groupIds": "long[] //设备群组ID"
}

请求示例

{
  "deviceSaasIds": "设备saasId",
  "topCategory": "一级品类，SaaS 1.5.0版本固定取值为 `zm`",
  "name": "自定义群组名称",
  "roomId": "房间 ID"
}

响应示例

{
  "groupPackageId": "自定义群组ID",
  "taskId": "设备状态数量，如果返回null，不用展示耗时操作，直接任务完成",
  "expiredSeconds": "任务过期剩余秒数，如果返回null，不用展示耗时操作，直接任务完成",
  "groupIds": "设备群组ID"
}

获取支持群组修改的设备

功能描述

获取已经加入群组设备以及未加入群组设备，用于群组编辑时，添加进入群组或者从群组从移除。

接口地址

GET /v1.0/illumination/group/package/{groupPackageId}/devices

请求参数

参数名 类型 参数类型 说明 是否必需
groupPackageId String url 群组 ID true

返回参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回十三位时间戳
result Object 返回结果

result参数说明

[
  {
    "deviceSaasId": "String //设备商照唯一ID",
    "deviceId": "String //设备ID，和硬件设备一一对应，由于设备重新绑定点位，导致在这里不唯一",
    "groupJoinStatus": "int //群组加入状态，0表示未加入，1表示已加入",
    "devicePurposeCode": "String //设备用途code"
  }
]

请求示例

{
  "groupPackageId": "群组ID"
}

响应示例

[
  {
    "deviceSaasId": "设备商照唯一ID",
    "deviceId": "设备ID，和硬件设备一一对应，由于设备重新绑定点位，导致在这里不唯一",
    "groupJoinStatus": "群组加入状态，0表示未加入，1表示已加入",
    "devicePurposeCode": "设备用途code"
  }
]

修改自定义群组

功能描述

修改自定义群组，支持批量添加、删除群组内的设备。

接口地址

PUT /v1.0/illumination/group/package

请求参数

参数名 类型 参数类型 说明 是否必需
roomId String body 空间 ID true
groupPackageId String body 自定义群组 ID true
name String body 群组名称 true
deviceSaasIds String[] body 设备saasId false

返回参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回十三位时间戳
result Object 返回结果

result参数说明

{
  "groupPackageId": "String //自定义群组ID",
  "taskId": "String //设备状态数量，如果返回null，不用展示耗时操作，直接任务完成",
  "expiredSeconds": "long //任务过期剩余秒数，如果返回null，不用展示耗时操作，直接任务完成",
  "groupIds": "long[] //设备群组ID"
}

请求示例

{
  "deviceSaasIds": "设备saasId"
  "name": "群组名称",
  "groupPackageId": "自定义群组ID",
}

响应示例

{
  "groupPackageId": "自定义群组ID",
  "taskId": "设备状态数量，如果返回null，不用展示耗时操作，直接任务完成",
  "expiredSeconds": "任务过期剩余秒数，如果返回null，不用展示耗时操作，直接任务完成",
  "groupIds": "设备群组ID"
}

删除自定义群组

功能描述

删除自定义群组。

接口地址

DELETE /v1.0/illumination/group/package/{groupPackageId}

请求参数

参数名 类型 参数类型 说明 是否必需
groupPackageId String url 自定义群组ID true

返回参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回十三位时间戳
result Object 返回结果

result参数说明

{
  "groupPackageId": "String //自定义群组ID",
  "taskId": "String //设备状态数量，如果返回null，不用展示耗时操作，直接任务完成",
  "expiredSeconds": "long //任务过期剩余秒数，如果返回null，不用展示耗时操作，直接任务完成",
  "groupIds": "long[] //设备群组ID"
}

请求示例

{
  "groupPackageId": "自定义群组ID"
}

响应示例

{
  "groupPackageId": "自定义群组ID",
  "taskId": "设备状态数量，如果返回null，不用展示耗时操作，直接任务完成",
  "expiredSeconds": "任务过期剩余秒数，如果返回null，不用展示耗时操作，直接任务完成",
  "groupIds": "设备群组ID"
}

获取空间下自定义群组列表

功能描述

分页获取指定空间下自定义群组列表。

接口地址

GET /v1.0/illumination/group/package

请求参数

参数名 类型 参数类型 说明 是否必需
roomId String body 房间 ID true
page int body 分页的页数 true
pageSize int body 每次获取的个数 true

返回参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回十三位时间戳
result Object 返回结果

result参数说明

{
  "total": "int",
  "list": [
    {
      "groupPackageId": "String //自定义群组ID",
      "roomId": "String //房间 ID",
      "topCategory": "String //一级品类code",
      "name": "String //自定义群组名称",
      "groupConfig": "String //群组配置",
      "type": "int //设备群组类型，1表示空群组，2表示标准群组，3表示组合群组",
      "deviceNum": "int //群组设备数量",
      "dps": {},
      "joinedGroups": [
        {
          "id": "long //设备群组ID",
          "name": "String //设备群组名称",
          "productId": "String //设备品类(产品)ID",
          "category": "String //设备群组meshCategory",
          "groupType": "int //设备群组协议类型",
          "type": "int //设备群组标准类型：0-单品群组，1-子设备群组",
          "localId": "String //群组localId",
          "meshId": "String //meshId",
          "iconUrl": "String //群组图标",
          "deviceNum": "int //设备数量",
          "localKey": "String //localKey",
          "masterNodeId": "String //主节点nodeId",
          "masterDevId": "String //主节点devId"
        }
      ]
    }
  ]
}

请求示例

{
  "pageSize": "每次获取的个数",
  "page": "分页的页数",
  "roomId": "房间 ID"
}

响应示例

{
  "total": "int",
  "list": [
    {
      "groupPackageId": "自定义群组ID",
      "roomId": "房间 ID",
      "topCategory": "一级品类code",
      "name": "自定义群组名称",
      "groupConfig": "群组配置",
      "type": "设备群组类型，1表示空群组，2表示标准群组，3表示组合群组",
      "deviceNum": "群组设备数量",
      "dps": {},
      "joinedGroups": [
        {
          "id": "设备群组ID",
          "name": "设备群组名称",
          "productId": "设备品类(产品)ID",
          "category": "设备群组meshCategory",
          "groupType": "设备群组协议类型",
          "type": "设备群组标准类型：0-单品群组，1-子设备群组",
          "localId": "群组localId",
          "meshId": "meshId",
          "iconUrl": "群组图标",
          "deviceNum": "设备数量",
          "localKey": "localKey",
          "masterNodeId": "主节点nodeId",
          "masterDevId": "主节点devId"
        }
      ]
    }
  ]
}

获取项目下自定义群组列表

功能描述

分页获取指定项目下自定义群组列表。

接口地址

GET /v1.0/illumination/project/group/package

请求参数

参数名 类型 参数类型 说明 是否必需
projectId String body 房间 ID true
page int body 分页的页数 true
pageSize int body 每次获取的个数 true

返回参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回十三位时间戳
result Object 返回结果

result参数说明

{
  "total": "int",
  "list": [
    {
      "groupPackageId": "String //自定义群组ID",
      "roomId": "String //房间 ID",
      "topCategory": "String //一级品类code",
      "name": "String //自定义群组名称",
      "groupConfig": "String //群组配置",
      "type": "int //设备群组类型，1表示空群组，2表示标准群组，3表示组合群组",
      "deviceNum": "int //群组设备数量",
      "dps": {},
      "joinedGroups": [
        {
          "ID": "long //设备群组ID",
          "name": "String //设备群组名称",
          "productId": "String //设备品类(产品)ID",
          "category": "String //设备群组meshCategory",
          "groupType": "int //设备群组协议类型",
          "type": "int //设备群组标准类型：0-单品群组，1-子设备群组",
          "localId": "String //群组localId",
          "meshId": "String //meshId",
          "iconUrl": "String //群组图标",
          "deviceNum": "int //设备数量",
          "localKey": "String //localKey",
          "masterNodeId": "String //主节点nodeId",
          "masterDevId": "String //主节点devId"
        }
      ]
    }
  ]
}

请求示例

{
  "pageSize": "每次获取的个数",
  "page": "分页的页数",
  "roomId": "房间 ID"
}

响应示例

{
  "total": "int",
  "list": [
    {
      "groupPackageId": "自定义群组ID",
      "roomId": "房间 ID",
      "topCategory": "一级品类code",
      "name": "自定义群组名称",
      "groupConfig": "群组配置",
      "type": "设备群组类型，1表示空群组，2表示标准群组，3表示组合群组",
      "deviceNum": "群组设备数量",
      "dps": {},
      "joinedGroups": [
        {
          "id": "设备群组ID",
          "name": "设备群组名称",
          "productId": "设备品类(产品)ID",
          "category": "设备群组meshCategory",
          "groupType": "设备群组协议类型",
          "type": "设备群组标准类型：0-单品群组，1-子设备群组",
          "localId": "群组localId",
          "meshId": "meshId",
          "iconUrl": "群组图标",
          "deviceNum": "设备数量",
          "localKey": "localKey",
          "masterNodeId": "主节点nodeId",
          "masterDevId": "主节点devId"
        }
      ]
    }
  ]
}

获取单个自定义群组详情

功能描述

获取单个自定义群组详情。

接口地址

GET /v1.0/illumination/group/package/{groupPackageId}

请求参数

参数名 类型 参数类型 说明 是否必需
groupPackageId String url 群组ID true

返回参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回十三位时间戳
result Object 返回结果

result参数说明

{
  "groupPackageId": "String //自定义群组ID",
  "roomId": "String //房间 ID",
  "topCategory": "String //一级品类code",
  "name": "String //自定义群组名称",
  "groupConfig": "String //群组配置",
  "type": "int //设备群组类型，1表示空群组，2表示标准群组，3表示组合群组",
  "deviceNum": "int //群组设备数量",
  "dps": [
    {
      "dpCode": "String //DP点代码",
      "dpName": "String //DP点名称",
      "dpValueStd": "String //DP当前值",
      "property": {
        "range": "String[] //描述属性值的取值范围"
      },
      "propertyDetail": {},
      "mode": "String //mode模式 例如 ro,rw  1.4.3新增",
      "dpFrom": "String"
    }
  ],
  "joinedGroups": [
    {
      "id": "long //设备群组ID",
      "name": "String //设备群组名称",
      "productId": "String //设备品类(产品)ID",
      "category": "String //设备群组meshCategory",
      "groupType": "int //设备群组协议类型",
      "type": "int //设备群组标准类型：0-单品群组，1-子设备群组",
      "localId": "String //群组localId",
      "meshId": "String //meshId",
      "iconUrl": "String //群组图标",
      "deviceNum": "int //设备数量",
      "localKey": "String //localKey",
      "masterNodeId": "String //主节点nodeId",
      "masterDevId": "String //主节点devId"
    }
  ]
}

请求示例

{
  "groupPackageId": "群组ID"
}

响应示例

{
  "groupPackageId": "自定义群组ID",
  "roomId": "房间 ID",
  "topCategory": "一级品类code",
  "name": "自定义群组名称",
  "groupConfig": "群组配置",
  "type": "设备群组类型，1表示空群组，2表示标准群组，3表示组合群组",
  "deviceNum": "群组设备数量",
  "dps": [
    {
      "dpCode": "DP点代码",
      "dpName": "DP点名称",
      "dpValueStd": "DP当前值",
      "property": {
        "range": "描述属性值的取值范围"
      },
      "propertyDetail": {},
      "mode": "mode模式 例如 ro,rw  1.4.3新增",
      "dpFrom": "String"
    }
  ],
  "joinedGroups": [
    {
      "id": "设备群组ID",
      "name": "设备群组名称",
      "productId": "设备品类(产品)ID",
      "category": "设备群组meshCategory",
      "groupType": "设备群组协议类型",
      "type": "设备群组标准类型：0-单品群组，1-子设备群组",
      "localId": "群组localId",
      "meshId": "meshId",
      "iconUrl": "群组图标",
      "deviceNum": "设备数量",
      "localKey": "localKey",
      "masterNodeId": "主节点nodeId",
      "masterDevId": "主节点devId"
    }
  ]
}

获取群组下设备的列表

功能描述

获取群组下设备列表。

接口地址

GET /v1.0/illumination/group/package/devices

请求参数

参数名 类型 参数类型 说明 是否必需
groupPackageId String body 自定义群组ID true
page int body 页数，不传取全部 false
pageSize int body 每页的数量，不传取全部 false

返回参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回十三位时间戳
result Object 返回结果

result参数说明

{
  "total": "int",
  "list": [
    {
      "deviceSaasId": "String //设备商照唯一ID",
      "deviceId": "String //设备ID，和硬件设备一一对应，由于设备重新绑定点位，导致在这里不唯一",
      "deviceName": "String //设备名称",
      "deviceType": "String //设备类型，详见DeviceTypeEnum",
      "deviceTypeValue": "int //设备类型值，详见DeviceTypeEnum",
      "topCategory": "String //产品所属大级分类。      详见 ProductCategoryEnum 的类型说明",
      "capability": "String //设备能力 ",
      "devicePower": "double //设备功率",
      "deviceStatus": "String //设备状态，详见DeviceAlarmTypeEnum",
      "deviceStatuses": "String[] //设备状态，详见AlarmTypeEnum",
      "installTime": "long //设备安装时间",
      "activeTime": "long //设备活跃时间",
      "productId": "String //设备品类(产品)ID",
      "roomId": "String //设备所属房间 ID",
      "roomName": "String //设备所属房间名称",
      "pointId": "String //设备所在点位ID",
      "ownerId": "String //所属设备家庭组ID",
      "switchInfo": [
        {
          "deviceId": "String //智能开关设备ID",
          "dpCode": "String //DP点代码"
        }
      ],
      "properties": [
        {
          "dpCode": "String //DP点代码",
          "dpName": "String //DP点名称",
          "dpValueStd": "String //DP当前值",
          "property": {
            "range": "String[] //描述属性值的取值范围"
          },
          "propertyDetail": {},
          "mode": "String //mode模式 例如 ro,rw  1.4.3新增",
          "dpFrom": "String"
        }
      ],
      "masterGroupJoinStatus": "int //主群组加入状态，0表示未加入，1表示已加入，2未加入群组的非照明设备",
      "currentBrightness": "int //设备所属房间的亮度阈值",
      "supportGroup": "boolean //是否支持群组",
      "switchStatus": "boolean //开关状态",
      "switchDpCode": "String //开关dpCode",
      "colourValue": "String //颜色值",
      "brightPercentValue": "String //亮度百分比值",
      "pointDeviceType": "int //点位图上设备类型",
      "switchCount": "int",
      "dpFrom": "String",
      "devicePurpose": {
        "id": "String //ID",
        "name": "String //名称",
        "code": "String //代码"
      },
      "industryPurpose": {
        "id": "String //ID",
        "name": "String //名称",
        "code": "String //代码"
      },
      "x": "String //点位x轴坐标",
      "y": "String //点位y轴坐标",
      "category": "String //产品所属二级分类",
      "iconUrl": "String //设备图标",
      "uuID": "String //设备uuID"
    }
  ]
}

请求示例

{
  "pageSize": "每页的数量,不传取全部",
  "page": "页数,不传取全部",
  "groupPackageId": "自定义群组ID"
}

响应示例

{
  "total": "int",
  "list": [
    {
      "deviceSaasId": "设备商照唯一ID",
      "deviceId": "设备ID，和硬件设备一一对应，由于设备重新绑定点位，导致在这里不唯一",
      "deviceName": "设备名称",
      "deviceType": "设备类型，详见DeviceTypeEnum",
      "deviceTypeValue": "设备类型值，详见DeviceTypeEnum",
      "topCategory": "产品所属大级分类。      详见 ProductCategoryEnum 的类型说明",
      "capability": "设备能力",
      "devicePower": "设备功率",
      "deviceStatus": "设备状态，详见DeviceAlarmTypeEnum",
      "deviceStatuses": "设备状态，详见AlarmTypeEnum",
      "installTime": "设备安装时间",
      "activeTime": "设备活跃时间",
      "productId": "设备品类(产品)ID",
      "roomId": "设备所属房间 ID",
      "roomName": "设备所属房间名称",
      "pointId": "设备所在点位ID",
      "ownerId": "所属设备家庭组ID",
      "switchInfo": [
        {
          "deviceId": "智能开关设备ID",
          "dpCode": "DP点代码"
        }
      ],
      "properties": [
        {
          "dpCode": "DP点代码",
          "dpName": "DP点名称",
          "dpValueStd": "DP当前值",
          "property": {
            "range": "描述属性值的取值范围"
          },
          "propertyDetail": {},
          "mode": "mode模式 例如 ro,rw  1.4.3新增",
          "dpFrom": "String"
        }
      ],
      "masterGroupJoinStatus": "主群组加入状态，0表示未加入，1表示已加入，2未加入群组的非照明设备",
      "currentBrightness": "设备所属房间的亮度阈值",
      "supportGroup": "是否支持群组",
      "switchStatus": "开关状态",
      "switchDpCode": "开关dpCode",
      "colourValue": "颜色值",
      "brightPercentValue": "亮度百分比值",
      "pointDeviceType": "点位图上设备类型",
      "switchCount": "int",
      "dpFrom": "String",
      "devicePurpose": {
        "id": "ID",
        "name": "名称",
        "code": "代码"
      },
      "industryPurpose": {
        "id": "ID",
        "name": "名称",
        "code": "代码"
      },
      "x": "点位x轴坐标",
      "y": "点位y轴坐标",
      "category": "产品所属二级分类",
      "iconUrl": "设备图标",
      "uuID": "设备uuID"
    }
  ]
}

群组控制

功能描述

通过 DP 功能点控制群组。

接口地址

POST /v1.0/illumination/group/package/control

请求参数

参数名 类型 参数类型 说明 是否必需
groupPackageId String body 群组ID true
dpCode String body dp点Code true
dpValue String body dp点值 true

返回参数

参数名 类型 说明
code Integer 响应码（详情见错误码章节），成功时为空
success Boolean 是否成功：（true：成功，false：失败）
msg String 请求失败的信息，成功时为空
t Long 返回十三位时间戳
result Object 返回结果

result参数说明

boolean{}

请求示例

{
  "dpValue": "dp点值",
  "dpCode": "dp点code",
  "groupPackageId": "群组ID"
}

响应示例

boolean{}

DeviceTypeEnum

deviceTypeValue deviceType 说明
-1 other 其他
0 intelligent_lamp 智能灯
1 gateway 网关设备
2 no_intelligent_lamp 非智能灯
3 switch 开关设备
4 sensor 传感器设备

错误码

以下为该接口常见的业务异常，更多的异常错误，参见全局错误码。

错误码 说明
500 系统错误
1106 非法权限
上一篇设备告警信息
下一篇智能规则
语言
简体中文
简体中文
English
400-881-8611
7×24小时服务热线
市场合作
marketing@tuya.com
业务合作
service@tuya.com
媒体联络
pr@tuya.com
关注“涂鸦智能”
涂鸦服务尽在掌握
关注“全球智能商业”
第一时间获取物联网资讯
联系我们加入我们TuyaExpoApp 商城TuyaGoTuyaGo服务商查询
法律声明隐私协议加州隐私权利声明服务条款廉正合规安全应急响应中心
©2014-2024 杭州涂鸦信息技术有限公司 版权
浙ICP备14011795号
浙B2-20210233号
浙公网安备33010602004238号
简体中文
简体中文
English