设备资源接口

设备资源是指由设备产生的数据,包括设备的设置参数与实时状态。一个设备具有多个资源,不同的资源表示不同设备属性的数据。例如,开关状态(plug_status)是智能插座的一个资源,表示智能插座当前是否通电,通过该资源,开发者可以查询插座的当前状态和远程控制插座。详细资源列表,可登录Aqara开发者平台,进入控制台-设备资源,即可查看当前已开放的设备资源列表。也可通过以下API接口查询。

查询设备资源详情

  • 接口intent:query.resource.info
  • 接口描述:根据设备的物模型查询该设备的资源属性详情。

  • 请求参数

名称 类型 是否必须 描述
model String 物模型
resourceId String 资源ID,不传将会返回所有已开放的资源ID以及详情
  • 请求示例
{
  "intent": "query.resource.info",
  "data": {
      "model": "lumi.switch.n1aeu1",
      "resourceId":"8.1.2044"
  }
}
  • 返回参数
名称 类型 描述
enums String 枚举值说明
resourceId String 资源id
minValue Integer 最小值
unit Integer 单位
access Integer 0-可读, 1-可写, 2-可读/可写
maxValue Integer 最大值
defaultValue String 当设备入网成功后的默认值。默认值仅部分设备配置
name String 资源名称,例如:断电记忆
description String 功能描述,例如:断电后重新上电,将会恢复断电前的开关状态
model String 设备的物模型,例如:lumi.switch.n1aeu1
  • 返回示例
{
    "code": 0,
    "message": "Success",
    "msgDetails": null,
    "requestId": "",
    "result": [
        {
            "enums": "0,1",
            "resourceId": "8.1.2044",
            "minValue": null,
            "unit": 1,
            "access": 0,
            "maxValue": null,
            "defaultValue": "0",
            "name": "插座负载检测(第2路)",
            "description": "插座负载检测,0:无负载。1:有负载",
            "model": "lumi.switch.n1aeu1"
        }
    ]
}

查询设备资源名称

  • 接口intent:query.resource.name
  • 接口描述:本接口用于根据设备ID查询该设备所有资源的默认名称(非该设备所有开放资源),该名称可通过“config.resource.info”接口进行修改。

  • 请求参数

名称 类型 是否必须 描述
subjectIds Array(String) 设备id数组,最大可同时查询50个。
  • 请求示例
{
    "intent": "query.resource.name",
    "data": {
        "subjectIds": ["virtual2.55266893697941"]
    }
}
  • 返回参数
名称 类型 描述
subjectId String 设备id
resourceId String 资源id
name String 名称
  • 返回示例
{
    "code": 0,
    "message": "Success",
    "msgDetails": null,
    "requestId": "",
    "result": [
        {
            "resourceId": "4.1.85",
            "name": "开关1",
            "subjectId": "virtual2.55266893697941"
        },
        {
            "resourceId": "4.2.85",
            "name": "开关2",
            "subjectId": "virtual2.55266893697941"
        }
    ]
}

修改设备资源信息

  • 接口intent:config.resource.info
  • 接口描述:本接口用于自定义修改设备资源的名称。例如:三键开关的第一键、第二键、第三键,可以根据用户的用途设置对应的名称,如客厅灯、卧室灯等,方便进行识别。

  • 请求参数

名称 类型 是否必须 描述
subjectId String 设备id数组,最大可同时查询50个。
resourceId String 资源id
name String 资源名称
  • 请求示例
{
    "intent": "config.resource.info",
    "data": {
        "subjectId":"virtual2.xxx",
        "resourceId":"14.7.111",
        "name":"小夜灯"
    }
}
  • 返回参数:无
  • 返回示例
{
    "code": 0,
    "message": "Success",
    "msgDetails": "",
    "requestId": "",
    "result": ""
}

查询设备资源最新状态

  • 接口intent:query.resource.value
  • 接口描述:本接口用于查询设备的指定资源的当前状态。

  • 请求参数

名称 类型 是否必须 描述
resources Array(Object) 资源列表,详情见resources说明

resources说明

名称 类型 是否必须 描述
subjectId String 设备id
resourceIds Array(String) 资源id数组,详见设备资源页面。
若为空查询设备下所有开放的资源值。
  • 请求示例
{
    "intent": "query.resource.value",
    "data": {
        "resources": [
            {
                "subjectId": "virtual2.11774113824794",
                "resourceIds": [
                    "4.1.85"
                ]
            }
        ]
    }
}
  • 返回参数
名称 类型 描述
subjectId String 设备id
resourceId String 资源id
value String 资源值
timeStamp Long 时间戳(毫秒)
  • 返回示例
{
    "code": 0,
    "message": "Success",
    "msgDetails": "",
    "requestId": "",
    "result": [
        {
            "timeStamp": 1617886614176,
            "resourceId": "4.1.85",
            "value": "1",
            "subjectId": "virtual2.11774113824794"
        }
    ]
}

更新设备资源(控制设备)

  • 接口intent:write.resource.device
  • 接口描述:更新设备资源,即设备控制或配置,如打开智能插座,即设置plug_status为1。详细资源列表,在Aqara开发者平台-控制台-设备资源页面,根据设备模型值或者设备名称查询详细资源描述。可写资源即可控制/配置。

  • 请求参数

名称 类型 是否必须 描述
subjectId String 设备id
resources Array 资源列表,详情见resources说明

resources说明:

名称 类型 是否必须 描述
resourceId String 资源id
value String 资源id对应的值,具体值定义,可参照控制台-设备资源页面,设备模型值对应资源的描述

注:data为数组格式

  • 请求示例
{
    "intent": "write.resource.device",
    "data": [
        {
            "subjectId": "lumi.158d000488d874",
            "resources": [
                {
                    "resourceId": "14.7.111",
                    "value": "1"
                }
            ]
        }
    ]
}
  • 返回参数:无
  • 返回示例
{
    "code": 0,
    "message": "Success",
    "msgDetails": "",
    "requestId": "",
    "result": ""
}

查询设备的历史数据

  • 接口intent:fetch.resource.history
  • 接口描述:本接口用于查询设备在某个时间段内的资源历史记录,最大可查询7天内的历史数据

  • 请求参数

名称 类型 是否必须 描述
subjectId String 设备id
resourceIds Array(String) 资源id数组,最大可同时支持100个资源ID
startTime String 查询开始时间(时间戳,单位:毫秒)
endTime String 查询结束时间(时间戳,单位:毫秒,默认当前时间)
size int 拉取数量,默认30,最小0,最大300
scanId String 循环拉取Id,每次拉取历史数据会返回此字段,若需继续往下拉取则携带此参数
  • 请求示例
{
    "intent": "fetch.resource.history",
    "data": {
        "subjectId": "lumi.158d00041a3e08",
        "resourceIds": [
            "4.1.85"
        ],
        "startTime": "1619850596000",
        "endTime": "1620811092000"
    }
}
  • 返回参数
名称 类型 描述
scanId String 下次继续拉取id
data Array(Object) 查询数据,详见data说明

data说明

名称 类型 描述
subjectId String 设备id
resourceId String 资源id
value String 资源ID的值记录,例如资源id:4.1.85的值为“1”,具体值定义,可参照控制台-设备资源页面,设备模型值对应资源的描述。
timeStamp Long 时间戳(毫秒)
  • 返回示例
{
    "code": 0,
    "message": "Success",
    "msgDetails": "",
    "requestId": "4665.51.16208112921411357",
    "result": {
        "data": [
            {
                "timeStamp": 1620810084129,
                "resourceId": "4.1.85",
                "value": "0",
                "subjectId": "lumi.158d00041a3e08"
            },
            {
                "timeStamp": 1620810083568,
                "resourceId": "4.1.85",
                "value": "1",
                "subjectId": "lumi.158d00041a3e08"
            },
            {
                "timeStamp": 1620810077058,
                "resourceId": "4.1.85",
                "value": "0",
                "subjectId": "lumi.158d00041a3e08"
            }
        ]
    }
}

查询设备的统计数据

  • 接口intent:fetch.resource.statistics
  • 接口描述:本接口用于查询设备资源的指定统计信息,如最小值,最大值,平均值等,最大可查询半年内的历史数据。具体值定义,可参照控制台-设备资源页面,支持的统计类型进行查看。

部分支持聚合的设备属性列表如下:

属性名称 可操作项
消耗的电能 求差值
负载功率 最小值,最大值,平均值
光照度 最小值,最大值,平均值
温度 最小值,最大值,平均值
湿度 最小值,最大值,平均值
大气压 最小值,最大值,平均值
如无线开关单击次数 频次
  • 请求参数
名称 类型 是否必须 描述
resources Array(Object) 资源列表,详情见resources说明
startTime String 查询开始时间(时间戳,单位:毫秒)
endTime String 查询结束时间(时间戳,单位:毫秒,默认当前时间)
dimension String 数据聚合的时间参数,例如30分钟的聚合数据。支持的聚合时间参数值范围(m表示分钟,h表示小时,d表示天,month表示月): 30m,1h, 2h,3h,4h,5h,6h,12h,1d,7d,month
aggrTypes Array(Num) 0-求差值;1-最小值;2-最大值;3-平均值;4-频次。若为空,则显示该属性支持的所有聚合项
size Integer 数据量限制,最小值:10,最大值:300。默认100
scanId String 循环拉取id,每次拉取历史数据会返回此字段,若需继续往下拉取则携带此参数

resources说明

名称 类型 是否必须 描述
subjectId String 对象id
resourceIds Array(String) 资源id数组,最大支持50个,详见设备资源页面
  • 请求参数
{
    "intent": "fetch.resource.statistics",
    "data": {
        "resources": {
            "subjectId": "lumi.158d000488d874",
            "aggrTypes": [1,2],
            "resourceIds": [
                "0.1.85"
            ]
        },
        "startTime": "1612789463000",
        "dimension": "30m"
    }
}
  • 返回参数
名称 类型 描述
scanId String 下次继续拉取id
data Array(Object) 查询数据,详见data说明

data说明

名称 类型 描述
timeStamp Long 时间戳,毫秒
resourceId String 资源id
value String 设备属性的值
subjectId String 对象id
aggrType Int 0-求差值;1-最小值;2-最大值;3-平均值;4-频次。
startTimeZone String 开始时间
endTimeZone String 结束时间
  • 返回示例
{
    "code": 0,
    "requestId": "844.28149.16099008675670099",
    "message": "Success",
    "msgDetails": null,
    "result": {
        "data": [
            {
                "timeStamp": 1623913188280,
                "resourceId": "0.1.85",
                "endTimeZone": 1623913200000,
                "value": "2651",
                "subjectId": "lumi.158d000488d874",
                "aggrType": 1,
                "startTimeZone": 1623911400000
            }
        ],
        "scanId": null
    }
}
Copyright © 2023 深圳绿米联创科技有限公司 all right reserved,powered by Gitbook文档修改时间: 2024-06-05 16:27:09

results matching ""

    No results matching ""