工业边缘数采一体机接口文档

该文档阅读对象为第三方开发者,文档包含三部分

订阅接口:第三方应用使用 MQTT 接口订阅数据,用于数据实时消费的场景

查询接口:第三方应用使用 HTTP 接口查询数据,用于数据按需查询的场景

数采接口:数采协议开发者使用该接口开发项目需要的数采协议,对接到边缘系统

术语定义

驱动(Driver)是对接具体通信协议的程序,比如modbus驱动、opcua驱动等。驱动具备上行和下行通信功能。驱动可以运行于边缘一体机,也可以运行于边缘一体机外部。

驱动编码(DriverCode)是驱动的编码系统,在项目中作为驱动的唯一标识符。

连接(Connection)是驱动和工业现场通信设备的一个通信通道,数据采集、下行控制等功能均通过该通道实现。

连接编码(ConnectionCode)是连接的编码系统,在驱动中作为连接的唯一标识符。

驱动编码(DriverCode)和连接编码(ConnectionCode)在项目中可以唯一索引到一个连接。

资产(Asset) 是工业设备、流程和设施的数字化表示,它可以是PLC、整个机床、生产线、棍床、汽车、电机等。每个资产都有与其关联的数据。例如,一套设备可能具有序列号、位置、品牌和型号以及安装日期。它还可能具有可用性、性能、质量、温度、压力等时间序列值。本产品支持空间类和设备类资产数字化管理,以及支持按空间或功能系统结构,进行资产层次管理。

资产编码(AssetCode是资产的编码系统,在项目中作为资产唯一标识符,方便与第三方做对接开发。

资产模板 (资产模型、资产类型 AssetTypeCode)是一个信息模板,资产可以基于模板快速创建。在每个资产模板中,用户可以配置定义业务属性、技术属性(时序)、技术指标(时序转换或聚合)、资产模板的父子关系、以及资产模板的可视模型(2D/3D)。注意:资产可以基于模板创建,也可以不依赖模板直接添加属性。

资产属性 是每个资产中包含工业数据的元数据。从数据管理的角度,资产属性分为四个类别:基础属性、管理属性、业务属性和技术属性。业务属性是具有静态特征的数据表示,例如设备生产厂家和产品规格型号,业务属性可以具有默认值,用户从资产模型创建的每个资产都包含该模型的属性默认值。技术属性是具有时序特征的数据表示,比如设备的振动频率,每个技术属性都有一个数据类型,并可以有一个单位。资产编码(AssetCode)+ 属性编码AttributeCode)在项目中可以唯一索引到一个属性。属性名称(AttributeName)可以是utf8中文,用于控制台显示等。属性分组名称(AttributeGroupName)用于属性归类,便于展示或检索。

数采点 经过 加工公式 处理 = 属性

订阅接口(MQTT)

订阅资产属性

  • MQTT topic 规范,{$AssetCode}{$AttributeCode} 替换为具体的标识符

#订阅某个具体的属性
usr/Module/DataDistribution/+/+/broadcast/+/+/metric/{$AssetCode}/{$AttributeCode}

#订阅某个资产Code下所有技术属性
usr/Module/DataDistribution/+/+/broadcast/+/+/metric/{$AssetCode}/#

#订阅所有技术属性
usr/Module/DataDistribution/+/+/broadcast/+/+/metric/#

#共享订阅所有技术属性,{$group-name}为共享组名称
$share/{$group-name}/usr/Module/DataDistribution/+/+/broadcast/+/+/metric/#

#注意 :
1、通过共享订阅可以实现多个client消费侧的负载均衡
2、mqtt链接断开后重连后需要重新subscribe
3、mqtt topic支持批量订阅
4、推荐客户端开启mqtt keepalive心跳,感知网络异常,做自动重连
  • 消息格式

{
    "Data":[
        {
            "AssetCode":"",
            "AttributeCode":"",
                                                "AttributeName":"",
            "AttributeGroupName":"",
            "Value":number/string,
            "Timestamp":timestamp_number,        //如1606800979591089792
                  "Quality":number,//保留字段,当前默认为0
        }
    ]
}

注: 过渡阶段,消息报文中保留了AttributeId, AssetId字段,后续会删除
  • 本地127.0.0.1订阅示例(免密)

例子:订阅所有资产下的所有技术属性的变更消息
/linkedge/gateway/build/bin/mosquitto_sub -p 10883 -t usr/Module/DataDistribution/+/+/broadcast/+/+/metric/# -v 

例子:订阅资产xxx下的所有技术属性的变更消息
/linkedge/gateway/build/bin/mosquitto_sub -p 10883 -t usr/Module/DataDistribution/+/+/broadcast/+/+/metric/xxx/# -v 

例子:订阅状态告警 & 资产告警
/linkedge/gateway/build/bin/mosquitto_sub -p 10883 -t usr/Module/Alarm/+/+/broadcast/# -v
  • 外部ip订阅示例(默认用户名:iottest,默认密码请联系接口人获取)

/linkedge/gateway/build/bin/mosquitto_sub -h 192.168.1.100 -p 10883 -u $username -P $password -t usr/Module/DataDistribution/+/+/broadcast/+/+/metric/# -v
  • 项目部署时,建议修改默认密码,修改方式如下

备份项目中的默认配置文件
mv /linkedge/gateway/build/bin/mosquitto_passwd /linkedge/gateway/build/bin/mosquitto_passwd.bak

生成新的配置文件(username,password按需修改)
touch /linkedge/gateway/build/bin/mosquitto_passwd

/linkedge/gateway/build/bin/mosquitto_passwd -b /linkedge/gateway/build/bin/mosquitto_pwdfile  $username  $password

重启LE使得配置生效
/linkedge/gateway/build/script/iot_gateway_start.sh

订阅告警事件

包含状态告警事件和资产告警事件

  • 边缘topic

# 状态告警
usr/Module/Alarm/+/+/broadcast/+/+/stateAlarm/generated // 产生
usr/Module/Alarm/+/+/broadcast/+/+/stateAlarm/recovered // 恢复
usr/Module/Alarm/+/+/broadcast/+/+/stateAlarm/handled   // 已处理
usr/Module/Alarm/+/+/broadcast/+/+/stateAlarm/ignored   // 已忽略

# 资产告警
usr/Module/Alarm/+/+/broadcast/+/+/assetAlarm/generated // 产生
usr/Module/Alarm/+/+/broadcast/+/+/assetAlarm/recovered // 恢复
usr/Module/Alarm/+/+/broadcast/+/+/assetAlarm/handled   // 已处理
usr/Module/Alarm/+/+/broadcast/+/+/assetAlarm/ignored   // 已忽略

# 注意
1、mqtt链接断开后重连后需要重新subscribe。
2、支持批量订阅topic
  • 消息内容

{
  "Id": "string",
  "SrcMsgId": "string",
  "AlarmId": "string",
  "SceneId": "string",
  "Category": "string",
  "Extras": {
    "Title": {"zh": "string", "en": "string"},
    "Kind": {"code":"string","name":{"zh":"string","en":"string"}},
    "Type": {"code":"string","name":{"zh":"string","en":"string"}},
    "Level": {"code":"string","name":{"zh":"string","en":"string"},"color":"string"},
    "Content": {"zh": "string", "en": "string"},
    "Custom": {}
  },      
  "Status": "unhandled|handled|ignored",
  "CreatedAt": number,
  "RecoveredAt": number,
  "Handler": "string",
  "HandledAt": number,
  "HandledComment": "string",
  "Trigger": {
    "Objects": [{
      "AssetCode": "string"
    }],
    "Meet": true|false
  }
}
  • 消息参数

参数名称

类型

描述

Id

String

告警事件ID。

SrcMsgId

String

原始消息ID。

AlarmId

String

告警定义ID。

SceneId

String

对应场景规则ID。

Category

String

告警类别。可能值:STATE_EVENT(状态告警)、ASSET_EVENT(资产告警)

Extras.Title

Object

告警标题。

Extras.Kind

Object

告警分类。

Extras.Type

Object

告警类型。

Extras.Level

Object

告警级别。

Extras.Content

Object

告警内容。

Extras.Custom

Object

告警自定义内容。

Status

String

当前状态。unhandled(待处理), handled(已确认), ignored(已忽略)

CreatedAt

Number

创建时间。

RecoveredAt

Number

恢复时间。

HandledAt

Number

处理时间。

Handler

String

处理人。

HandledComment

String

处理说明。

Trigger.Objects

Object

触发对象。Category为ASSET_EVENT是包含AssetCode。

Trigger.Meet

Boolean

是否满足触发条件。满足为告警事件,否则为告警撤销事件。

  • 本地127.0.0.1订阅示例

例子:订阅状态告警 & 资产告警
/linkedge/gateway/build/bin/mosquitto_sub -p 10883 -t usr/Module/Alarm/+/+/broadcast/# -v &

查询接口(HTTP)

创建认证标识

创建认证标识。认证标识用于认证下一步API调用,有效时间为30分钟。当传入已有JWEToken,此API将刷新认证标识。

  • 请求语法

POST /2021-06-10/tokens

{
        "Username": "string",
        "Password": "string",
  "JWEToken": "string"
}

  • 请求参数

参数名称

类型

是否必选

位置

描述

Username

String

Body

用户名。必须与密码同时设置,不可与JWEToken同时设置。

Password

String

Body

密码。必须与用户名同时设置,不可与JWEToken同时设置。

JWEToken

String

Body

已有认证标识。用于刷新认证标识。不可与用户名密码同时设置。

  • 响应语法

HTTP/1.1 StatusCode
{
        "JWEToken": "string"
}
  • 响应参数

参数名称

类型

描述

StatusCode

Number

HTTP状态码。返回200表示成功,返回其它状态码表示失败。

JWEToken

String

认证Token。

  • 示例

$ curl -i -d '{"Username":"xxx","Password":"xxxx"}' -X POST http://localhost/2021-06-10/tokens

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Tue, 13 Oct 2020 06:42:53 GMT
Content-Length: 697

{"JWEToken":"{\"protected\":\"eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0\",\"aad\":\"eyJleHAiOiIyMDIwLTEwLTEzVDE1OjEyOjUzKzA4OjAwIiwiaWF0IjoiMjAyMC0xMC0xM1QxNDo0Mjo1MyswODowMCJ9\",\"encrypted_key\":\"bdiLa6nV88zWPkgrDrJKF1ILUbQWSoJU51gri8R_QWdBYM_TWvwf9uzTt8ImVFS8w22jmVtvAEnTOy0010ioYyJdwN4-PNWLcz5h2_CIPGERJJbbLX7JCZKus4JfEkOm1mGUGOrJcvtRQvVTluluRGkM47ZPiuCVtBfnJFtpm7CZOZpOITZ7MgCImyYUyPd5effcePYFaedb61Z1Bs01waVnrSXLjh4FgF994-E3qYI12wQ_cAY0Nc_bicR45J0L47AW1V6M956pakpMkbVcl6S1li6gdwAyA8sMWZeNWRPhGH8FQMQrvXEbxPyyTxhPsKkfoQhzR70p3VK_of_b7w\",\"iv\":\"xjHlTRyIyVsNlm7X\",\"ciphertext\":\"3v-59oZUzhsDgAih4EMqk9gHn49yLDxLgjJCEDFCXXNx8s-p8-IbtjV-TQ\",\"tag\":\"jqUjxKd5Xzkk41D8FzY-dQ\"}"}

连接

查询

【TODO】当前未支持

查询连接列表。

  • 请求语法

GET /2021-06-10/drivers/{DriverCode}connections/state
  • 请求参数

参数名称

类型

是否必选

位置

描述

JWEToken

String

Header

认证Token。使用CreateAuthToken创建。

DriverCode

String

Path

驱动编码。

ConnectionCodes

[]String

Query

属性编码数组,数组最大元素个数为100,批量查询,精确匹配;如果未给出,则将驱动下所有连接的状态返回。格式:

ConnectionCodes=aaa&

ConnectionCodes=bbb&...

  • 响应语法

HTTP/1.1 StatusCode
{
        "ConnectionStates": [{
    "Code": "string", // 连接编码
                "State": number,         // 连接状态,-2:异常;-1:未部署;0:正常
    "AssetState": [120, 130], // 下属设备的状态,正常120,总数130        
  }]
}
  • 响应参数

参数名称

类型

描述

StatusCode

Number

HTTP状态码。返回200表示成功,返回其它状态码表示失败。

ConnectionStates.Code

String

连接编码。

ConnectionStates.State

Number

连接状态,-2:异常;-1:未部署;0:正常。

ConnectionStates.AssetState

[]

Number

下属设备的状态,二维数组的第0个元素表示正常设备数,第1个元素表示设备总数。

  • 示例

资产-模板

查询

查询资产模板列表。

  • 请求语法

GET /2021-06-10/assettypes
  • 请求参数

参数名称

类型

是否必选

位置

描述

JWEToken

String

Header

认证Token。使用CreateAuthToken创建。

Name

String

Query

资产模板名称。支持全模糊匹配。

Code

String

Query

资产模板编码。支持全模糊匹配。

Page

Number

Query

页码。从1开始。默认值为1。

Size

Number

Query

每页数量。最大值为100。默认值为30。

  • 响应语法

HTTP/1.1 StatusCode
{
        "TotalCount": number,
        "AssetTypes": [{
    "Name": "string",
                "Code": "string"                
  }]
}
  • 响应参数

参数名称

类型

描述

StatusCode

Number

HTTP状态码。返回200表示成功,返回其它状态码表示失败。

TotolCount

Number

总数量。

AssetType.Name

String

资产模板名称。

AssetType.Code

String

资产模板编号。

  • 示例

curl -i -H JWEToken:"{\"protected\":\"eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0\",\"aad\":\"eyJleHAiOiIyMDIxLTA2LTIwVDE5OjIxOjEwKzA4OjAwIiwiaWF0IjoiMjAyMS0wNi0yMFQxODo1MToxMCswODowMCJ9\",\"encrypted_key\":\"vzrnjCa84iJSuM9Q0YIAMmgmPpcVQoyb89wL3BK0gBeU9cQp_R39lpQVi9caaPCLBYH8Sbnfck4pzdnMVEuzP4YTIXtBlBb7bYjMft5JCB_qY609SPgUux6V3K0xlEecLo8D_WRPm6zhrJUENf-a8rBE3CM_59l3WbLr_IqavNnME07b26zfcMC5z_yMRhhajDGVpzSjdHUgP5fm9MuwMDuTIPYg30vPPJfEJatGGtWAlaCYMIKHa6AVwFn3929GtKonjI4ltjgusPDanTxjSHCZUx32P3lcE6ss8N0lDNwKnA3VdUBlTf5WcAvyB1A3UjxzKcBReEEJh2kng79gZQ\",\"iv\":\"KxI4LVTVxeJUF7dP\",\"ciphertext\":\"v0fiVHxzryub-mZT9UKiRwBuzukDT6CTChLrWyBUjkZd3X0vaCuLKIufWQ\",\"tag\":\"t2juVpRp9E0yP0VKaD9lxg\"}" -X GET "http://11.158.188.72/2021-06-10/assettypes?Name=测距&Code=DL100_LASER_PD_FB&Page=1&Size=30"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Sun, 20 Jun 2021 10:58:41 GMT
Content-Length: 82

{"TotalCount":1,"AssetTypes":[{"Code":"DL100_LASER_PD_FB","Name":"激光测距"}]}

资产-元数据

查询元数据

查询资产基础元数据。

  • 请求语法

GET /2021-06-10/assets
  • 请求参数

参数名称

类型

是否必选

位置

描述

JWEToken

String

Header

认证Token。使用CreateAuthToken创建。

Code

String

Query

资产编码。全模糊查询。

Codes

[]String

Query

资产编码数组,数组元素个数最多100,精确匹配。格式:Codes=aaa&Codes=bbb&...

ParentCodes

[]String

Query

父资产编码数组,数组元素个数最多100,精确匹配。格式:ParentCodes=aaa&ParentCodes=bbb&...

TypeCodes

[]String

Query

资产模板编码数组,数组元素个数最多100,精确匹配。格式:TypeCodes=aaa&TypeCodes=bbb&...

Page

Number

Query

页码。从1开始。默认值为1。

Size

Number

Query

每页数量。最大值为100。默认值为30。

  • 响应语法

HTTP/1.1 StatusCode
{
        "TotalCount": number,
        "Assets": [{
                "Code": "string",
                "Name": "string",
    "Descs": "string",
                "TypeCode": "string",
                "TypeName": "string",
                "ParentCode": "string",
                "ParentName": "string",
                "CreatedAt": number,
        }]
}
  • 响应参数

参数名称

类型

描述

StatusCode

Number

HTTP状态码。返回200表示成功,返回其它状态码表示失败。

TotolCount

Number

总数量。

Assets.Code

String

资产编码。

Assets.Name

String

资产名称。

Assets.Descs

String

资产多语言描述。

Assets.TypeCode

String

资产模板编码。

Assets.TypeName

String

资产模板名称。

Assets.ParentCode

String

父资产编码。

Assets.ParentName

String

父资产名称。

Assets.CreatedAt

Number

创建时间。

  • 示例

curl -i -H JWEToken:"{\"protected\":\"eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0\",\"aad\":\"eyJleHAiOiIyMDIxLTA2LTIwVDE5OjIxOjEwKzA4OjAwIiwiaWF0IjoiMjAyMS0wNi0yMFQxODo1MToxMCswODowMCJ9\",\"encrypted_key\":\"vzrnjCa84iJSuM9Q0YIAMmgmPpcVQoyb89wL3BK0gBeU9cQp_R39lpQVi9caaPCLBYH8Sbnfck4pzdnMVEuzP4YTIXtBlBb7bYjMft5JCB_qY609SPgUux6V3K0xlEecLo8D_WRPm6zhrJUENf-a8rBE3CM_59l3WbLr_IqavNnME07b26zfcMC5z_yMRhhajDGVpzSjdHUgP5fm9MuwMDuTIPYg30vPPJfEJatGGtWAlaCYMIKHa6AVwFn3929GtKonjI4ltjgusPDanTxjSHCZUx32P3lcE6ss8N0lDNwKnA3VdUBlTf5WcAvyB1A3UjxzKcBReEEJh2kng79gZQ\",\"iv\":\"KxI4LVTVxeJUF7dP\",\"ciphertext\":\"v0fiVHxzryub-mZT9UKiRwBuzukDT6CTChLrWyBUjkZd3X0vaCuLKIufWQ\",\"tag\":\"t2juVpRp9E0yP0VKaD9lxg\"}" -X GET "http://11.158.188.72/2021-06-10/assets?Code=DK1_1A0010RB&Page=1&Size=30"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Sun, 20 Jun 2021 10:57:31 GMT
Content-Length: 741

{"TotalCount":4,"Assets":[{"Code":"DK1_1A0010RB1","Name":"1A0010RB1","Descs":"JY_DK1_1A0010RB1","TypeCode":"IDENT_JY_PD_FB","TypeName":"","ParentCode":"","ParentName":"","CreatedAt":1623404682182},{"Code":"DK1_1A0010RB7","Name":"1A0010RB7","Descs":"JY_DK1_1A0010RB7","TypeCode":"IDENT_JY_PD_FB","TypeName":"","ParentCode":"","ParentName":"","CreatedAt":1623404682182},{"Code":"DK1_1A0010RB","Name":"DK1_1A0010R","Descs":"JY_DK1_1A0010RB","TypeCode":"IDENT_JY_PD_FB","TypeName":"","ParentCode":"","ParentName":"","CreatedAt":1623412036990},{"Code":"DK1_1A0010RB_TM1","Name":"1A0010RB-TM1","Descs":"JY_DK1_1A0010RB-TM1","TypeCode":"DRIVE_LENZE8400PN_PD_FB","TypeName":"","ParentCode":"DK1_1A0010RB","ParentName":"","CreatedAt":1623412036990}]}

查询子资产

查询某资产下所有子资产列表。

  • 请求语法

GET /2021-06-10/childassets
  • 请求参数

参数名称

类型

是否必选

位置

描述

JWEToken

String

Header

认证Token。使用CreateAuthToken创建。

Code

String

Query

资产编码。返回该资产下所有子资产。

  • 响应语法

HTTP/1.1 StatusCode
{
        "TotalCount": number,
        "Assets": [{
                "Code": "string"                
  }]
}
  • 响应参数

参数名称

类型

描述

StatusCode

Number

HTTP状态码。返回200表示成功,返回其它状态码表示失败。

TotolCount

Number

总数量。

Asset.Code

String

资产编号。

  • 示例

curl -i -H JWEToken:"{\"protected\":\"eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0\",\"aad\":\"eyJleHAiOiIyMDIxLTA2LTIwVDE5OjIxOjEwKzA4OjAwIiwiaWF0IjoiMjAyMS0wNi0yMFQxODo1MToxMCswODowMCJ9\",\"encrypted_key\":\"vzrnjCa84iJSuM9Q0YIAMmgmPpcVQoyb89wL3BK0gBeU9cQp_R39lpQVi9caaPCLBYH8Sbnfck4pzdnMVEuzP4YTIXtBlBb7bYjMft5JCB_qY609SPgUux6V3K0xlEecLo8D_WRPm6zhrJUENf-a8rBE3CM_59l3WbLr_IqavNnME07b26zfcMC5z_yMRhhajDGVpzSjdHUgP5fm9MuwMDuTIPYg30vPPJfEJatGGtWAlaCYMIKHa6AVwFn3929GtKonjI4ltjgusPDanTxjSHCZUx32P3lcE6ss8N0lDNwKnA3VdUBlTf5WcAvyB1A3UjxzKcBReEEJh2kng79gZQ\",\"iv\":\"KxI4LVTVxeJUF7dP\",\"ciphertext\":\"v0fiVHxzryub-mZT9UKiRwBuzukDT6CTChLrWyBUjkZd3X0vaCuLKIufWQ\",\"tag\":\"t2juVpRp9E0yP0VKaD9lxg\"}" -X GET "http://11.158.188.72/2021-06-10/childassets?Code=ACCDD"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Sun, 20 Jun 2021 11:01:16 GMT
Content-Length: 51

{"TotalCount":1,"Assets":[{"Code":"DK1_1A0010RC"}]}

资产-技术属性-元数据

查询

查询资产技术属性元信息。

  • 请求语法

GET /2021-06-10/assets/{AssetCode}/attributeinfos
  • 请求参数

参数名称

类型

是否必选

位置

描述

JWEToken

String

Header

认证Token。使用CreateAuthToken创建。

AssetCode

String

Path

资产编码。

AttributeCode

String

Query

属性编码。支持模糊查询。

AttributeCodes

[]String

Query

属性编码数组,数组最大元素个数为100,批量查询,精确匹配。格式:

AttributeCodes=aaa&AttributeCodes=bbb&...

GroupNames

[]String

Query

属性组名数组,数组最大元素个数为100,批量查询,精确匹配。格式:GroupNames=aaa&GroupNames=bbb&...。

Page

Number

Query

页码。从1开始。默认值为1。

Size

Number

Query

每页数量。最大值为100。默认值为30。

  • 响应语法

HTTP/1.1 StatusCode
{
        "TotalCount": number,
        "AttributeInfos": [{
                "Writable": "t", // f 不可写;t 可写
                "MeasureUnit": "string",
                "MinValue": "string",
                "MaxValue": "string",
    "AssetCode": "string",
                "AttributeName": "string",
    "DataType":"Bool",
                "AttributeGroupName": "string",
    "AttributeCode": "string",
    "AttributeDescs": "string",
    "AttributeGroupDescs": "string",
    "EnumValue": "string",
    "Precision": number,
                "CreatedAt": number,
    "ModifiedAt": number
        }]
}
  • 响应参数

参数名称

类型

描述

StatusCode

Number

HTTP状态码。返回200表示成功,返回其它状态码表示失败。

TotalCount

Number

技术属性总数量。

AttributeInfos.Writable

String

是否可写,“t”表示可写,“f”表示不可写。

AttributeInfos.MeasureUnit

String

度量单位。

AttributeInfos.MinValue

String

允许最小值。

AttributeInfos.MaxValue

String

允许最大值。

AttributeInfos.AssetCode

String

资产编码。

AttributeInfos.AttributeName

String

技术属性名称。

AttributeInfos.DataType

String

属性数据类型,Bool/Int/Double/Enum/Text/Time

AttributeInfos.AttributeGroupName

String

资产属性组名。

AttributeInfos.AttributeCode

String

技术属性编码。

AttributeInfos.AttributeDescs

String

技术属性多语言描述。

AttributeInfos.AttributeGroupDescs

String

技术属性组多语言描述。

AttributeInfos.EnumValue

String

枚举值。

AttributeInfos.Precision

Number

精度。

AttributeInfos.CreatedAt

Number

创建时间。

AttributeInfos.ModifiedAt

Number

更新时间。

  • 示例

curl -i -H JWEToken:"{\"protected\":\"eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0\",\"aad\":\"eyJleHAiOiIyMDIxLTA2LTIwVDE5OjIxOjEwKzA4OjAwIiwiaWF0IjoiMjAyMS0wNi0yMFQxODo1MToxMCswODowMCJ9\",\"encrypted_key\":\"vzrnjCa84iJSuM9Q0YIAMmgmPpcVQoyb89wL3BK0gBeU9cQp_R39lpQVi9caaPCLBYH8Sbnfck4pzdnMVEuzP4YTIXtBlBb7bYjMft5JCB_qY609SPgUux6V3K0xlEecLo8D_WRPm6zhrJUENf-a8rBE3CM_59l3WbLr_IqavNnME07b26zfcMC5z_yMRhhajDGVpzSjdHUgP5fm9MuwMDuTIPYg30vPPJfEJatGGtWAlaCYMIKHa6AVwFn3929GtKonjI4ltjgusPDanTxjSHCZUx32P3lcE6ss8N0lDNwKnA3VdUBlTf5WcAvyB1A3UjxzKcBReEEJh2kng79gZQ\",\"iv\":\"KxI4LVTVxeJUF7dP\",\"ciphertext\":\"v0fiVHxzryub-mZT9UKiRwBuzukDT6CTChLrWyBUjkZd3X0vaCuLKIufWQ\",\"tag\":\"t2juVpRp9E0yP0VKaD9lxg\"}" -X GET "http://11.158.188.72/2021-06-10/assets/CON1_1A001001/attributeinfos?Page=1&Size=2"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Sun, 20 Jun 2021 11:02:37 GMT
Content-Length: 726

{"TotalCount":72,"AttributeInfos":[{"Writable":"t","MeasureUnit":"","MinValue":"","MaxValue":"","AssetCode":"CON1_1A001001","AttributeName":"Spare_0","DataType":"Bool","AttributeGroupName":"BOOL_DEMO","AttributeCode":"BOOL_DEMO.Spare_0","AttributeDescs":"Spare_0","AttributeGroupDescs":"","EnumValue":"","Precision":0,"CreatedAt":1626417324033,"ModifiedAt":1626417324033},{"Writable":"f","MeasureUnit":"","MinValue":"","MaxValue":"","AssetCode":"CON1_1A001001","AttributeName":"Spare_1","DataType":"Bool","AttributeGroupName":"BOOL_DEMO","AttributeCode":"BOOL_DEMO.Spare_1","AttributeDescs":"Spare_1","AttributeGroupDescs":"","EnumValue":"","Precision":0,"CreatedAt":1626417324033,"ModifiedAt":1626417324033}]}

资产-技术属性-数据值

查询

查询单个资产的技术属性值。

  • 请求语法

GET /2021-06-10/assets/{AssetCode}/attributes
  • 请求参数

参数名称

类型

是否必选

位置

描述

JWEToken

String

Header

认证Token。使用CreateAuthToken创建。

AssetCode

String

Path

资产编码。

AttributeCodes

[]String

Query

属性编码数组,最大个数为100。格式:

AttributeCodes=aaa&AttributeCodes=bbb&...

Since

String

Query

起始时间。ISO 8601格式: YYYY-MM-DDTHH:MM:SSZ。如2021-04-22T22:02:46+07:00(2021-04-22T22:02:46Z默认东7区)。

Until

String

Query

结束时间。ISO 8601格式: YYYY-MM-DDTHH:MM:SSZ。如2021-04-22T22:02:46+07:00(2021-04-22T22:02:46Z默认东7区)。

Type

String

Query

查询类型。有效值:

  • last:最新值。

  • first:最旧值。

  • min:最小值。

  • max:最大值。

  • mean:平均值。

  • distinct:不同值。

  • count:总数。

Interval

String

Query

分组时间间隔。如1ns|u|ms|s|m|h|d|w。指定时必须指定Type,且至少指定Since或Util中的一个。若Util为空则返回截止到当前时间的分组。时间隔间内没有数据点时默认返回null,可通过Fill指定没有数据点时的返回值。

Fill

String

Query

指定时必须同时指定Interval,表示分组时间间隔不包含数据点时的返回值。可选值:

  • 任意数值:用这个数字返回没有数据点的时间间隔的数据。

  • linear:返回没有数据点的时间间隔的线性插值的结果。

  • none:不返回在时间间隔里没有点的数据。

  • previous:返回时间间隔的前一个间隔的数据。

OrderBy

String

Query

指定返回值按时间排序方式。可选值:

  • asc:升序。默认值,表示第一个具有最早时间戳。

  • desc:降序。

Offset

Number

Query

数据偏移量。默认值为0,表示不偏移。

Limit

Number

Query

返回数据量。默认值为0,表示不限制。

  • 响应语法

HTTP/1.1 StatusCode
{
        "Results": [{
                "Series": [{
                        "AssetCode": "string",
      "AttributeCode": "string",
                        "Columns": [
                                "time",
                                "value",
        "quality"
                        ],
                        "Values": [
                                [
                                        number, // 时间戳,与Columns[0]字段对应。
                                        "string"|boolean|number, // 属性值,与Columns[1]字段对应。
          number // 质量码,与Columns[2]字段对应。
                                ]                                
                        ]
                }]
        }]
}
  • 响应参数

参数名称

类型

描述

StatusCode

Number

HTTP状态码。返回200表示成功,返回其它状态码表示失败。

Series.AssetCode

String

资产编码。

Series.AttributeCode

String

属性编码。

Series.Columns[0]

String

标识Values[i][0]的返回内容。固定为time,表示Values[i][0]的返回内容为时间戳。

Series.Columns[1]

String

标识Values[i][1]的返回内容。固定为value,表示Values[i][1]的返回内容为属性值。

Series.Columns[2]

String

标识Values[i][2]的返回内容。固定为quality,表示Values[i][1]的返回内容为质量码。查询条件Type为聚合类型时(mean, distinct)不返回此列。

Series.Values

[][]Any

返回值数组。[]Any内容与Columns对应。

  • 示例

$ curl -v -H JWEToken:"{\"protected\":\"eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0\",\"aad\":\"eyJleHAiOiIyMDIxLTAzLTI2VDE4OjU2OjM1KzA4OjAwIiwiaWF0IjoiMjAyMS0wMy0yNlQxODoyNjozNSswODowMCJ9\",\"encrypted_key\":\"Xl0ZCP62O_ZXt5OSt_lkep7aEyxoY_zGwMOr0dkZR7rVWwQ-Rj3e05gj5emxLToGUgr2cqN_N8dEz5msu9Ul0hMCa-cZGM7O3N4mZHGxc8f5LXCGf4SfTWlhvnund1orOIuKBTh3vP86PgCNTaZssqWaE2B9BQ2corVn5FVtCCVdFWadTyracOLz9r2vaChUup1XOu3UoQQ9q13b1wFhEt8tdP8NqaBcyNDzHk73Clq0V6qCtdFzJeUf9aVaI87Pq2y3Nj1UY99x03BzZ8KjaRtH6smUG1x9IZm1QTDEsHWF__dGlXIQ-STKRcWwJ-rKeCTCSC6A8qbPjbi4DFdXjQ\",\"iv\":\"2zx_4cDgzCCdNtr3\",\"ciphertext\":\"VL3v9AL1RYq40lLTZInMcCktwI2yw1L_m5x44LDtLw4txWHCkK2d90Witg\",\"tag\":\"5_Ra1Nk-GJU839EO9ujynQ\"}" -G --data-urlencode 'AttributeCodes=HMI_Control_No' --data-urlencode 'Type=last'  http://localhost/2021-06-10/assets/DK1_1B0890SL/attributes
*   Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to 127.0.0.1 (127.0.0.1) port 80 (#0)
> GET /2021-06-10/assets/DK1_1B0890SL/attributes?AttributeCodes=HMI_Control_No&Type=last HTTP/1.1
> Host: 127.0.0.1
> User-Agent: curl/7.64.1
> Accept: */*
> 
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Date: Tue, 15 Jun 2021 18:22:16 GMT
< Content-Length: 174
< 
* Connection #0 to host 127.0.0.1 left intact
{"Results":[{"StatementId":0,"Series":[{"AssetCode":"DK1_1B0890SL","AttributeCode":"HMI_Control_No","Columns":["time","last","quality"],"Values":[[1623781332627,3443,0]]}]}]}* Closing connection 0

批量查询

查询多个资产的多个技术属性值。

  • 请求语法

POST /2021-06-10/attributes/search
  • 请求参数

{
        "Attributes": [{
                        "AssetCode": "string",
                        "AttributeCode": "string"
        }],
        "Since": "string",
        "Until": "string",
        "Type": "string",
        "Interval": "string",
        "Fill": "string",
        "OrderBy": "string",
        "Offset": number,
        "Limit": number
}

参数名称

类型

是否必选

位置

描述

JWEToken

String

Header

认证Token。使用CreateAuthToken创建。

Attributes

[]Object

Body

待查询值的属性列表,数组最大个数为100。格式:[{"AssetCode": "string", "AttributeCode": "string"}]

其中AssetCode为资产编码,AttributeCode为属性编码。

Since

String

Body

起始时间。ISO 8601格式: YYYY-MM-DDTHH:MM:SSZ。如2021-04-22T22:02:46+07:00(2021-04-22T22:02:46Z默认东7区)。

Until

String

Body

结束时间。ISO 8601格式: YYYY-MM-DDTHH:MM:SSZ。如2021-04-22T22:02:46+07:00(2021-04-22T22:02:46Z默认东7区)。

Type

String

Body

查询类型。有效值:

  • last:最新值。

  • first:最旧值。

  • min:最小值。

  • max:最大值。

  • mean:平均值。

  • distinct:不同值。

  • count:总数。

Interval

String

Body

分组时间间隔。如1ns|u|ms|s|m|h|d|w。指定时必须指定Type,且至少指定Since或Util中的一个。若Util为空则返回截止到当前时间的分组。时间隔间内没有数据点时默认返回null,可通过Fill指定没有数据点时的返回值。

Fill

String

Body

指定时必须同时指定Interval,表示分组时间间隔不包含数据点时的返回值。可选值:

  • 任意数值:用这个数字返回没有数据点的时间间隔的数据。

  • linear:返回没有数据点的时间间隔的线性插值的结果。

  • none:不返回在时间间隔里没有点的数据。

  • previous:返回时间间隔的前一个间隔的数据。

OrderBy

String

Body

指定返回值按时间排序方式。可选值:

  • asc:升序。默认值,表示第一个具有最早时间戳。

  • desc:降序。

Offset

Number

Body

数据偏移量。默认值为0,表示不偏移。

Limit

Number

Body

返回数据量。默认值为0,表示不限制。

  • 响应语法

HTTP/1.1 StatusCode
{
        "Results": [{
                "Series": [{
                        "AssetCode": "string",
      "AttributeCode": "string",
                        "Columns": [
                                "time",
                                "value",
        "quality"
                        ],
                        "Values": [
                                [
                                        number, // 时间戳,与Columns[0]字段对应。
                                        "string"|boolean|number, // 属性值,与Columns[1]字段对应。
          number // 质量码,与Columns[2]字段对应。
                                ]                                
                        ]
                }]
        }]
}
  • 响应参数

参数名称

类型

描述

StatusCode

Number

HTTP状态码。返回200表示成功,返回其它状态码表示失败。

Series.AssetCode

String

资产编码。

Series.AttributeCode

String

属性编码。

Series.Columns[0]

String

标识Values[i][0]的返回内容。固定为time,表示Values[i][0]的返回内容为时间戳。

Series.Columns[1]

String

标识Values[i][1]的返回内容。固定为value,表示Values[i][1]的返回内容为属性值。

Series.Columns[2]

String

标识Values[i][2]的返回内容。固定为quality,表示Values[i][1]的返回内容为质量码。查询条件Type为聚合类型时(mean, distinct)不返回此列。

Series.Values

[][]Any

返回值数组。[]Any内容与Columns对应。

  • 示例

$ curl -v -H JWEToken:"{\"protected\":\"eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0\",\"aad\":\"eyJleHAiOiIyMDIxLTAzLTI2VDE4OjU2OjM1KzA4OjAwIiwiaWF0IjoiMjAyMS0wMy0yNlQxODoyNjozNSswODowMCJ9\",\"encrypted_key\":\"Xl0ZCP62O_ZXt5OSt_lkep7aEyxoY_zGwMOr0dkZR7rVWwQ-Rj3e05gj5emxLToGUgr2cqN_N8dEz5msu9Ul0hMCa-cZGM7O3N4mZHGxc8f5LXCGf4SfTWlhvnund1orOIuKBTh3vP86PgCNTaZssqWaE2B9BQ2corVn5FVtCCVdFWadTyracOLz9r2vaChUup1XOu3UoQQ9q13b1wFhEt8tdP8NqaBcyNDzHk73Clq0V6qCtdFzJeUf9aVaI87Pq2y3Nj1UY99x03BzZ8KjaRtH6smUG1x9IZm1QTDEsHWF__dGlXIQ-STKRcWwJ-rKeCTCSC6A8qbPjbi4DFdXjQ\",\"iv\":\"2zx_4cDgzCCdNtr3\",\"ciphertext\":\"VL3v9AL1RYq40lLTZInMcCktwI2yw1L_m5x44LDtLw4txWHCkK2d90Witg\",\"tag\":\"5_Ra1Nk-GJU839EO9ujynQ\"}" -d '{"Attributes":[{"AssetCode":"DK1_1B0890SL","AttributeCode":"HMI_Control_No"}],"Type":"last"}'  http://localhost/2021-06-10/attributes/search
*   Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to 127.0.0.1 (127.0.0.1) port 80 (#0)
> POST /2021-06-10/attributes/search HTTP/1.1
> Host: 127.0.0.1
> User-Agent: curl/7.64.1
> Accept: */*
> Content-Length: 92
> Content-Type: application/x-www-form-urlencoded
> 
* upload completely sent off: 92 out of 92 bytes
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Date: Tue, 15 Jun 2021 18:28:01 GMT
< Content-Length: 174
< 
* Connection #0 to host 127.0.0.1 left intact
{"Results":[{"StatementId":0,"Series":[{"AssetCode":"DK1_1B0890SL","AttributeCode":"HMI_Control_No","Columns":["time","last","quality"],"Values":[[1623781676342,3591,0]]}]}]}* Closing connection 0

更新

更新资产技术属性值。

  • 请求语法

PATCH /2021-06-10/assets/{AssetCode}/attributes/{AttributeCode}
{
        "Value": "string"
}
  • 请求参数

参数名称

类型

是否必选

位置

描述

JWEToken

String

Header

认证Token。使用CreateAuthToken创建。

AssetCode

String

Path

资产编码。

AttributeCode

String

Path

技术属性编码

Value

String

Body

属性值。统一使用字符串传值。

  • 响应语法

HTTP/1.1 StatusCode
  • 响应参数

参数名称

类型

描述

StatusCode

Number

HTTP状态码。返回200表示成功,返回其它状态码表示失败。

  • 示例

$ curl -v -H JWEToken:"{\"protected\":\"eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0\",\"aad\":\"eyJleHAiOiIyMDIxLTAzLTI2VDE4OjU2OjM1KzA4OjAwIiwiaWF0IjoiMjAyMS0wMy0yNlQxODoyNjozNSswODowMCJ9\",\"encrypted_key\":\"Xl0ZCP62O_ZXt5OSt_lkep7aEyxoY_zGwMOr0dkZR7rVWwQ-Rj3e05gj5emxLToGUgr2cqN_N8dEz5msu9Ul0hMCa-cZGM7O3N4mZHGxc8f5LXCGf4SfTWlhvnund1orOIuKBTh3vP86PgCNTaZssqWaE2B9BQ2corVn5FVtCCVdFWadTyracOLz9r2vaChUup1XOu3UoQQ9q13b1wFhEt8tdP8NqaBcyNDzHk73Clq0V6qCtdFzJeUf9aVaI87Pq2y3Nj1UY99x03BzZ8KjaRtH6smUG1x9IZm1QTDEsHWF__dGlXIQ-STKRcWwJ-rKeCTCSC6A8qbPjbi4DFdXjQ\",\"iv\":\"2zx_4cDgzCCdNtr3\",\"ciphertext\":\"VL3v9AL1RYq40lLTZInMcCktwI2yw1L_m5x44LDtLw4txWHCkK2d90Witg\",\"tag\":\"5_Ra1Nk-GJU839EO9ujynQ\"}" -d '{"Value":"3445"}' -X PATCH http://localhost/2021-06-10/assets/DK1_1B0890SL/attributes/HMI_Control_No
*   Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to 127.0.0.1 (127.0.0.1) port 80 (#0)
> PATCH /2021-06-10/assets/DK1_1B0890SL/attributes/HMI_Control_No HTTP/1.1
> Host: 127.0.0.1
> User-Agent: curl/7.64.1
> Accept: */*
> Content-Length: 16
> Content-Type: application/x-www-form-urlencoded
> 
* upload completely sent off: 16 out of 16 bytes
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Date: Tue, 15 Jun 2021 18:35:34 GMT
< Content-Length: 0
< 
* Connection #0 to host 127.0.0.1 left intact
* Closing connection 0

告警事件

查询

查询告警事件,包含状态告警事件和资产告警事件。

  • 协议:HTTP

GET /2021-06-10/alarmevents
  • 请求参数

参数名称

类型

是否必选

位置

描述

JWEToken

String

Header

认证Token。使用CreateAuthToken创建。

Ids

[]String

Query

告警事件ID数组。最大个数为100。格式:Ids=0aa5&Ids=5877&...

Category

String

Query

查询数据类别。可选值:STATE_EVENT(查询状态告警)、ASSET_EVENT(查询资产告警)。

Status

String

Query

告警事件状态。可选值:unhandled, handled, ignored。

Recovered

Boolean

Query

是否已恢复。可选值:true, false。

Extras

Map

Query

额外信息查询的键和值。格式如Extras[key]=value,其中key格式为{Title,zh},表示Extras.Title.zh,{Custom,Name,0}表示Extras.Custom.Name[0].。具体请参阅https://www.postgresql.org/docs/12/functions-json.html

AssetCode

String

Query

资产Code。支持模糊查询。

Recursive

Boolean

Query

是否查询子资产。指定时必须指定AssetCode,AssetCode不支持模糊查询。

Since

String

Query

起始时间。ISO 8601格式: YYYY-MM-DDTHH:MM:SSZ。如2021-04-22T22:02:46+07:00(2021-04-22T22:02:46Z默认东7区)。

Until

String

Query

结束时间。ISO 8601格式: YYYY-MM-DDTHH:MM:SSZ。如2021-04-22T22:02:46+07:00(2021-04-22T22:02:46Z默认东7区)。

Page

Number

Query

页码。从1开始。默认值为1。

Size

Number

Query

每页数量。最大值为100。默认值为30。

  • 响应语法

HTTP/1.1 StatusCode
{
        "TotalCount": number,
        "AlarmEvents": [{
                "Id": "string",
                "SrcMsgId": "string",
                "AlarmId": "string",
                "SceneId": "string",
                "Category": "string",
                "Extras": {
                        "Title": {"zh": "string","en": "string"},
                        "Kind": {"code":"string","name":{"zh":"string","en":"string"}},
      "Type": {"code":"string","name":{"zh":"string","en":"string"}},
                        "Level": {"code":"string","name":{"zh":"string","en":"string"},"color":"string"},
                        "Content": {"zh": "string","en": "string"},
      "Custom": {}
                },
                "Status": "unhandled|handled|ignored",
                "CreatedAt": number,
                "RecoveredAt": number,
                "Handler": "string",
                "HandledAt": number,
                "HandledComment": "string",
                "Trigger": {
                        "Objects": [{
                                "AssetCode": "string",
        "AttributeCode":"string",
                        }],
                        "Meet": true | false
                }
        }]
}
  • 响应参数

参数名称

类型

描述

StatusCode

Number

HTTP状态码。返回200表示成功,返回其它状态码表示失败。

TotalCount

Number

总告警事件数。

AlarmEvent.Id

String

告警事件ID,代表产生的告警记录。

AlarmEvent.SrcMsgId

String

原始消息ID。Category为ASSET_EVENT时包含。

AlarmEvent.AlarmId

String

告警定义ID,如ID1代表水温告警,ID2代表震动告警。

AlarmEvent.SceneId

String

对应场景规则ID。

AlarmEvent.Category

String

告警类别。可能值:STATE_EVENT(状态告警)、ASSET_EVENT(资产告警)

AlarmEvent.Extras.Title

Object

告警标题。

AlarmEvent.Extras.Kind

Object

告警分类。

AlarmEvent.Extras.Type

Object

告警类型。

AlarmEvent.Extras.Level

Object

告警级别。

AlarmEvent.Extras.Content

Object

告警内容。

AlarmEvent.Extras.Custom

Object

告警自定义字段。

AlarmEvent.Status

String

当前状态。unhandled(待处理), handled(已确认), ignored(已忽略)

AlarmEvent.CreatedAt

Number

创建时间。

AlarmEvent.RecoveredAt

Number

恢复时间。

AlarmEvent.

HandledAt

Number

处理时间。

AlarmEvent.Handler

String

处理人。

AlarmEvent.

HandledComment

String

处理说明。

AlarmEvent.

Trigger.Objects

Object

触发对象。Category为STATE_EVENT时包含AssetCode和AttributeCode,为ASSET_EVENT是包含AssetCode。

AlarmEvent.Trigger.Meet

Boolean

是否满足触发条件。满足为告警事件,否则为告警撤销事件。

创建

创建告警事件。

  • 请求语法

POST /2021-06-10/alarmevents

{
  "SrcMsgId": "string",
  "Category": "ASSET_EVENT",
  "Extras": {
    "Title": {"zh": "string", "en": "string"},
    "Kind": {"code":"string","name":{"zh":"string","en":"string"}},
    "Type": {"code":"string","name":{"zh":"string","en":"string"}},
    "Level": {"code":"string","name":{"zh":"string","en":"string"},"color":"string"},
    "Content": {"zh": "string", "en": "string"},
    "Custom": {} // User custom content.
  },      
  "CreatedAt": number,
  "Trigger": {
    "Objects": [{
      "AssetCode": "string"
    }],
    "Meet": true|false
  }
}

  • 请求参数

参数名称

类型

是否必选

位置

描述

JWEToken

String

Header

认证Token。使用CreateAuthToken创建。

SrcMsgId

String

Body

原始消息ID。标识某设备的某类告警。

Category

String

Body

告警类别。当前只支持ASSET_EVENT(资产告警)。

Extra.Title

Object

Body

告警标题。支持多语言。

Extra.Level

Object

Body

告警级别。支持多语言。

Extra.Kind

Object

Body

告警分类。支持多语言。

Extra.Type

Object

Body

告警类型。支持多语言。

Extra.Content

Object

Body

告警内容。支持多语言。

Extra.Custom

Object

Body

告警自定义字段。最多支持2个层级。

CreatedAt

Number

Body

告警产生时间。默认为调用接口的时间。

Trigger.Objects

[]Object

Body

触发对象。Category为ASSET_EVENT时包含AssetCode。

Trigger.Meet

Boolean

Body

是否满足触发条件。满足时产生告警,不满足时撤销告警。

  • 响应语法

HTTP/1.1 StatusCode
{
  "Id": "string"
}
  • 响应参数

参数名称

类型

描述

StatusCode

Number

HTTP状态码。返回200表示成功,返回其它状态码表示失败。

AlarmEvent.Id

String

告警事件ID。

AlarmEvent.CreatedAt

Number

创建时间。

创建-批量

批量创建告警事件。

  • 请求语法

POST /2021-06-10/alarmevents/bulk

[{
  "SrcMsgId": "string",
  "Category": "ASSET_EVENT",
  "Extras": {
    "Title": {"zh": "string", "en": "string"},
    "Kind": {"code":"string","name":{"zh":"string","en":"string"}},
    "Type": {"code":"string","name":{"zh":"string","en":"string"}},
    "Level": {"code":"string","name":{"zh":"string","en":"string"},"color":"string"},
    "Content": {"zh": "string", "en": "string"},
    "Custom": {} // User custom content.
  },      
  "CreatedAt": number, // required when Tirgger.Meet is true
  "RecoveredAt": number, // required when Tirgger.Meet is false
  "Trigger": {
    "Objects": [{
      "AssetCode": "string"
    }],
    "Meet": true|false
  }
}]

  • 请求参数

参数名称

类型

是否必选

位置

描述

JWEToken

String

Header

认证Token。使用CreateAuthToken创建。

Category

String

Body

告警类别。当前只支持ASSET_EVENT(资产告警)。

SrcMsgId

String

Body

原始消息ID。资产告警消息唯一标识,Category为ASSET_EVENT时必须指定。

Extra.Title

Object

Body

告警标题。支持多语言。

Extra.Level

Object

Body

告警级别。支持多语言。

Extra.Kind

Object

Body

告警分类。支持多语言。

Extra.Type

Object

Body

告警类型。支持多语言。

Extra.Content

Object

Body

告警内容。支持多语言。

Extra.Custom

Object

Body

告警自定义字段。

CreatedAt

Number

Body

告警产生时间。满足告警触发条件时为必须。

RecoveredAt

Number

Body

告警恢复时间。不满足告警触发条件时为必须。

Trigger.Objects

[]Object

Body

触发对象。Category为ASSET_EVENT时必须包含AssetCode。

Trigger.Meet

Boolean

Body

是否满足触发条件。满足时产生告警,不满足时撤销告警。

  • 响应语法

HTTP/1.1 StatusCode
{
  "Rows": number
}
  • 响应参数

参数名称

类型

描述

StatusCode

Number

HTTP状态码。返回200表示成功,返回其它状态码表示失败。

Rows

Number

受影响的行数。

  • 示例

## 创建告警
$ curl -v -H 'JWEToken:{"protected":"eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0","aad":"eyJleHAiOiIyMDIxLTAzLTI5VDExOjE1OjE1KzA4OjAwIiwiaWF0IjoiMjAyMS0wMy0yOVQxMDo0NToxNSswODowMCJ9","encrypted_key":"u9iV1gihhcGe53JLghjLQck3xQrEDPdNd-Bb0ZZ86yOIvqwAqgLHj3Xgn7uP1HC91q8XErua6o090xFEoqpI0LDIh00Z0B9z2bhe2kHzoNhOoqRWuQdH-3oDObj7uWHw18K2RQSsK4TThfIFTTkoqAoHNfMlE_f7SWSCvbGJgcvfFXt2ilAPb33kDRliHdyxwakwNW7LslQfdtM9qaEeHlJzuVPYQ29eockNdZhMgVmsROzF1aBMwAENgg_cRDTx3pZOHGJEN8jt1WiXumKO1dWpWs6p7gbtabdQOoNRKB7Zq3_bwuyDxX468TRClPxIk9yEAdXQKQp0UbQvPNZQrw","iv":"DOsZV3ZKQGMS3APk","ciphertext":"voRtRhBf7oeU9d_dcUokNbwqiryZ4ECZObpGubs9COA_N5-qhXKRgrkHlA","tag":"bak50biL857G3T8axdpnrg"}' -d '[{"SrcMsgId":"MSG_DeviceID_030901_1","Category":"ASSET_EVENT","Extras":{"Title":{"zh":"资产告警1","en":"asset_alarm"},"Type":{"code":"alarm_code1","name":{"zh":"告警类型1","en":"alarmType1"}},"Level":{"code":"Content1","name":{"zh":"级别1","en":"Level1"},"color":"color1"},"Content":{"zh":"Content","en":"Content"},"Custom":{}},"CreatedAt":1616483961000,"Trigger":{"Objects":[{"DeviceId":"DeviceID_030901"}],"Meet":true}}]' -X POST http://127.0.0.1/2021-06-10/alarmevents/bulk

* About to connect() to 127.0.0.1 port 80 (#0)
*   Trying 127.0.0.1...
* Connected to 127.0.0.1 (127.0.0.1) port 80 (#0)
> POST /2021-06-10/alarmevents/bulk HTTP/1.1
> User-Agent: curl/7.29.0
> Host: 127.0.0.1
> Accept: */*
> Content-Length: 432
> Content-Type: application/x-www-form-urlencoded
> 
* upload completely sent off: 432 out of 432 bytes
< HTTP/1.1 200 OK
< Content-Length: 10
< Content-Type: application/json; charset=utf-8
< Date: Mon, 29 Mar 2021 02:44:08 GMT
< 
* Connection #0 to host 127.0.0.1 left intact
{"Rows":1}


## 恢复告警
$ curl -v -H 'JWEToken:{"protected":"eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0","aad":"eyJleHAiOiIyMDIxLTAzLTI5VDExOjE1OjE1KzA4OjAwIiwiaWF0IjoiMjAyMS0wMy0yOVQxMDo0NToxNSswODowMCJ9","encrypted_key":"u9iV1gihhcGe53JLghjLQck3xQrEDPdNd-Bb0ZZ86yOIvqwAqgLHj3Xgn7uP1HC91q8XErua6o090xFEoqpI0LDIh00Z0B9z2bhe2kHzoNhOoqRWuQdH-3oDObj7uWHw18K2RQSsK4TThfIFTTkoqAoHNfMlE_f7SWSCvbGJgcvfFXt2ilAPb33kDRliHdyxwakwNW7LslQfdtM9qaEeHlJzuVPYQ29eockNdZhMgVmsROzF1aBMwAENgg_cRDTx3pZOHGJEN8jt1WiXumKO1dWpWs6p7gbtabdQOoNRKB7Zq3_bwuyDxX468TRClPxIk9yEAdXQKQp0UbQvPNZQrw","iv":"DOsZV3ZKQGMS3APk","ciphertext":"voRtRhBf7oeU9d_dcUokNbwqiryZ4ECZObpGubs9COA_N5-qhXKRgrkHlA","tag":"bak50biL857G3T8axdpnrg"}' -d '[{"SrcMsgId":"MSG_DeviceID_030901_1","Category":"ASSET_EVENT","RecoveredAt":1616902656000,"Trigger":{"Meet":false}}]' -X POST http://127.0.0.1/2021-06-10/alarmevents/bulk

* About to connect() to 127.0.0.1 port 80 (#0)
*   Trying 127.0.0.1...
* Connected to 127.0.0.1 (127.0.0.1) port 80 (#0)
> POST /2021-06-10/alarmevents/bulk HTTP/1.1
> User-Agent: curl/7.29.0
> Host: 127.0.0.1
> Accept: */*
> Content-Length: 116
> Content-Type: application/x-www-form-urlencoded
> 
* upload completely sent off: 116 out of 116 bytes
< HTTP/1.1 200 OK
< Content-Length: 10
< Content-Type: application/json; charset=utf-8
< Date: Mon, 29 Mar 2021 02:48:04 GMT
< 
* Connection #0 to host 127.0.0.1 left intact
{"Rows":1}

告警确认-批量

确认告警事件。

  • 请求语法

POST /2021-06-10/alarmevents/handlings

{
        "Ids": ["string"],
        "Status": "string",
        "Handler": "string",
        "Comment": "string"
}
  • 请求参数

参数名称

类型

是否必选

位置

描述

JWEToken

String

Header

认证Token。使用CreateAuthToken创建。

Ids

[]String

Body

逗号分隔的告警事件ID数组。最大个数为100。

Status

String

Body

更新状态。有效值为handled和ignored。

Handler

String

Body

处理人。

Comment

String

Body

处理评论。

  • 响应语法

HTTP/1.1 StatusCode
  • 响应参数

参数名称

类型

描述

StatusCode

Number

HTTP状态码。返回200表示成功,返回其它状态码表示失败。

其他

查询 连接和设备的映射关系

查询连接列表

  • 请求语法

GET /2021-06-10/driver-conn-asset-map
  • 请求参数

参数名称

类型

是否必选

位置

描述

JWEToken

String

Header

认证Token。使用CreateAuthToken创建。

  • 响应参数

HTTP/1.1 StatusCode
{
        "TotalCount": number,
        "Drivers": [
    {
      "Code": "string",        
      "Connections":[
        {
                                        "Code":"string",
          "Assets":[
                  {
                    "Code":"string"
            }
          }
        }
      ]
    }
  ]
}

参数名称

类型

描述

TotalCount

Number

连接总数

Drviers.Code

String

驱动编码

Drviers.Connections.Code

String

连接编码

Drviers.Connections.Assets.Code

String

资产编码

  • 示例

HTTP API错误码

HTTP状态码(Status)

错误码(Code)

描述

200 OK

接口调用成功。

201 Created

请求成功并且服务器创建了新的资源。

400 Bad Request

BadRequest

语义有误,当前请求无法被服务器理解,除非进行修改,否则客户端不应该重复提交该请求。

详细的错误信息,请查看本文下方表 1表格。

401 Unauthorized

Unauthorized

目标资源的身份认证Cookie不正确,需要重新调用CreateAuthCookie接口更新Cookie,否则将无法继续调用其他API。

403 Forbidden

Forbidden

服务器已经理解请求,但拒绝执行请求。需要进行权限校验,确认当前登录用户是否有权限调用请求API。

404 Not Found

NotFound

请求失败,未在服务器上发现请求所希望得到的资源。需要确认请求参数是否正确。

405 Method Not Allowed

MethodNotAllowed

请求行中指定的请求方法不能被用于请求相应的资源。例如,不支持使用POST方法。

500 Internal Server Error

InternalServerError

服务器内部错误。

详细的错误信息,请查看本文下方表 2表格。

说明 出现500 Internal Server Error错误时,请优先根据错误信息提示和日志内容排查问题,若仍无法解决问题,您可以提交工单联系我们获取技术支持。

503 Service Unavailable

ServiceUnavailable

由于临时的服务器维护或服务器过载,因此服务器当前无法处理请求。

表 1. 400 Bad Request状态码详细错误信息

错误码(Code)

描述

InvalidParameter

请求参数有误。请输入正确的请求参数,然后重试。

MissingParameter

缺少必要的请求参数。请输入正确的请求参数,然后重试。

表 2. 500 Internal Server Error状态码详细错误信息

错误码(Code)

描述

Cookie.Handler.Create

无法创建身份认证Cookie。

Cookie.Set

无法保存身份认证Cookie。

HMAC

认证消息的哈希算法(HMAC)运算失败。

Connection.Create

无法与上游服务建立连接。

Connection.Lost

与上游服务的链接已断开。

Message.Create

无法创建发送到上游服务的消息。

Message.SendAndReply

发送消息到上游服务,或接收上游服务消息异常。

Message.InvalidReply

上游服务响应的格式不正确。

Message.FailedReply

上游服务的响应结果显示,调用接口失败。

当上游服务返回的错误码(Code)不在本行下方Service.{name}.{error}格式的错误列表中时,会返回该错误码。

Service.NotExist

上游服务不存在。通常上游服务未启动或者退出时,报此错误码。

Service.Data.Get

无法从数据中心获取数据。

Service.Data.Set

无法设置数据到数据中心。

Service.Data.KeyNotExist

无法从数据中心获取数据,因为数据的key不存在。

Service.Thing.Call

调用设备接口失败。详细说明请参见设备接入状态码

Service.Function.NotExist

被调函数不存在。

Service.Function.Timeout

函数执行超时。

Service.Scene.NotExist

场景规则不存在。

Service.Scene.NotAtLevel0

禁止执行操作,因为场景联动的运行状态为非Normal模式,例如Sceneless模式等,请更换为Normal模式后重试。

HTTP API调用示例

CreateAuthToken

OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"Username\":\"xxx\",\"Password\":\"xxx\"}");
Request request = new Request.Builder()
  .url("http://localhost/2021-06-10/tokens")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

// Get JWEToken from body.

ListAlarmEvents

// Add JWEToken header for authentication.

OkHttpClient client = new OkHttpClient().newBuilder().build();
Request request = new Request.Builder()
  .url("http://localhost/2021-06-10/alarmevents?Size=1")
  .method("GET", null)
  .addHeader("JWEToken", "{\"protected\":\"eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0\",\"aad\":\"eyJleHAiOiIyMDIwLTEwLTA0VDAxOjUzOjEyKzA4OjAwIiwiaWF0IjoiMjAyMC0xMC0wNFQwMToyMzoxMiswODowMCJ9\",\"encrypted_key\":\"iBqKB_50TmzNaI04RpfIi_5N_Mk_9-N9dDUFf_jkDk1qQFZSAF4_Q6mlwco2rrI6WZpZGmt4YDsyLJhMOyGpWq6mvq49gFErmH-UYQ80WJbDtlyIVWUrX3picCpUXS9StX_sAI7pO6gRIQvsFsUxvFG_04evL3EtPWrdZnnqhS0PsLjPmf7jF7u1drp6VN5Q81lFeOWnVEYlP5TqUMkD5_o2bpQoyeubWYndM2T3Ka8MPPZK-66duRTe9Jgxtn--vqwqp91EDWsuBFgwquScb488O0ev1cb3EX_vbWRaN6Nj-6egvwNimAkWcA15A3wRK6oJV2H9UasXB-HPjdXPdA\",\"iv\":\"OzSvzFEOn3WpDC-D\",\"ciphertext\":\"RRevInGzkL7EWjFP4gpEG6B1epaU88boFb6LMGSvsw1p4K_ozp6_jNwnQg\",\"tag\":\"WlFWpioEMoPDeM09oohuVA\"}")
  .build();
Response response = client.newCall(request).execute();

数采接口

  • 提供C、Java SDK。

  • 点位数据由ID, Value,Quality, Timestamp组成。

点位上报

  • reportPoints接口

点位控制

  • setPoints接口

Java SDK数据结构

/**
 * A point representing a property of some thing.
 */
public class Point {

    /**
     * The quality level of a point.
     */
    public enum Quality {
        /**
         * Quality level corresponding to good.
         */
        GOOD(0x00),
        /**
         * Quality level corresponding to backup.
         */
        BACKUP(0x08),
        /**
         * Quality level corresponding to uncertain.
         */
        UNCERTAIN(0x40),
        /**
         * Quality level corresponding to last usable.
         */
        LAST_USABLE(0x48),
        /**
         * Quality level corresponding to bad.
         */
        BAD(0xC0),
        /**
         * Quality level corresponding to communicate failure.
         */
        COMM_FAILURE(0xC8),
        /**
         * Quality level corresponding to device failure.
         */
        DEVICE_FAILURE(0xD0),
        /**
         * Quality level corresponding to last known.
         */
        LAST_KNOWN(0xD8);

        private int code;

        Quality(int code) {
            this.code = code;
        }

        /**
         * Return the quality code.
         */
        public int getCode() {
            return code;
        }
    }

    /**
     * Construct and initialize a point with zero values.
     */
    public Point();

    /**
     * Construct and initialize a point with the specified id, value, {@link Quality#GOOD}
     * quality and current timestamp in nanosecond.
     */
    public Point(String id, Object value);

    /**
     * Construct and initialize a point with the specified id, value, {@link Quality} and
     * current timestamp in nanosecond.
     */
    public Point(String id, Object value, Quality quality);

    /**
     * Construct and initialize a point with the specified id, value, {@link Quality} and
     * timestamp in nanosecond.
     */
    public Point(String id, Object value, Quality quality, long timestamp);

    /**
     * Return the id of the point.
     */
    public String getId();

    /**
     * Return the value of the point.
     */
    public Object getValue();

    /**
     * Return the quality of the point.
     */
    public Quality getQuality();

    /**
     * Return the timestamp in nanosecond at which the point generated.
     */
    public long getTimestamp();

    /**
     * Set the id of the point.
     */
    public void setId(String id);

    /**
     * Set the value of the point.
     */
    public void setValue(Object value);

    /**
     * Set the quality of the point.
     */
    public void setQuality(Quality quality);

    /**
     * Set the timestamp of the point in nanosecond.
     */
    public void setTimestamp(long timestamp);

    /**
     * Perform the check(s) on the specified {@link Point} using its internal properties.
     */
    public static void check(Point point);
}

Java SDK接口

/**
 * <p>
 * The main programming interface for the DataFactory service. An application
 * must instantiate this class and implement the callbacks to interact with
 * the DataFactory service.
 * </p>
 *
 * <p>
 * A typical flow to use the client would be like the below, and since methods
 * in this class are thread-safe, <code>connect</code>, <code>reportPointIds</code>,
 * <code>reportPoints</code> can be called from different threads.
 * </p>
 *
 * <pre>
 * {@code
 *     DataFactoryClient client = new DataFactoryClient(...);
 *
 *     client.connect();
 *
 *     ...
 *     client.reportPointIds(ids);
 *     ...
 *     client.reportPoints(points);
 *     ...
 *
 *     client.destroy()
 * }
 * </pre>
 */
public class DataFactoryClient {

    /**
     * The callback for handling the messages from DataFactory service. Methods
     * are invoked on worker threads.
     */
    public interface Callback {

        /**
         * Set the values of a list of points. Invoked from DataFactory service
         * for updating points' values.
         *
         * @param client the {@link DataFactoryClient} object.
         * @param points the points which containing ids and values to set.
         * @throws DataFactoryException
         */
        void setPoints(DataFactoryClient client, List<Point> points) throws DataFactoryException;
    }

    /**
     * Instantiates a new client. It looks for DATAFACTORY_ADDR environment variable
     * as the endpoint address of the DataFactory service, or <code>address</code> in
     * config.json in current working directory.
     *
     * @param id the client id to which points bound.
     * @param callback a callback for handling messages from DataFactory service.
     */
    public DataFactoryClient(String id, Callback callback);

    /**
     * Instantiates a new client.
     *
     * @param id the client id to which points bound.
     * @param callback a callback for handling messages from DataFactory service.
     * @param addr the endpoint address of the DataFactory service.
     */
    public DataFactoryClient(String id, Callback callback, String addr);

    /**
     * Connect to the DataFactory service.
     *
     * @throws DataFactoryException
     */
    public void connect() throws DataFactoryException;

    /**
     * Report point ids. This should be called once after connect().
     *
     * @param ids the ids of all kinds of points.
     * @throws DataFactoryException
     */
    public void reportPointIds(String[] ids) throws DataFactoryException;

    /**
     * Report points.
     *
     * @param points the points.
     * @throws DataFactoryException
     */
    public void reportPoints(Point[] points) throws DataFactoryException;

    /**
     * Destroy the client and release resources.
     *
     * @throws DataFactoryException
     */
    public void destroy() throws DataFactoryException;
}