1. 查询节点下的设备列表
- 1.1. 接口定义
- 1.2. 请求示例
- 1.3. 返回值
  - 1.3.1. 成功 (Status 200)
  - 1.3.2. 失败-节点不存在 (Status 404)
2. 查询设备信息
- 2.1. 接口定义
- 2.2. 请求示例
- 2.3. 返回值
  - 2.3.1. 成功 (Status 200)
  - 2.3.2. 失败-设备不存在 (Status 404)
3. 根据设备ID查询设备信息
- 3.1. 接口定义
- 3.2. 请求示例
- 3.3. 返回值
  - 3.3.1. 成功 (Status 200)
  - 3.3.2. 失败-设备不存在 (Status 404)
4. 查询设备属性
- 4.1. 接口定义
- 4.2. 请求示例
- 4.3. 返回值
  - 4.3.1. 成功 (Status 200)
  - 4.3.2. 失败-设备不存在 (Status 404)
5. 根据设备ID查询设备属性
- 5.1. 接口定义
- 5.2. 请求示例
- 5.3. 返回值
  - 5.3.1. 成功 (Status 200)
  - 5.3.2. 失败-设备不存在 (Status 404)
6. 设置设备期望属性
- 6.1. 接口定义
  - 16.1.1 根据nodeId+deviceType+deviceName设置设备期望属性
  - 16.1.1 根据deviceId设置设备期望属性
- 请求体(JSON)
6.2 请求示例
6.3 返回值
- 6.3.1 成功（Status 200），返回body为空
- 6.3.2 失败-未指定属性/非空属性值为空/物模型定义非法（Status 400）
- 6.3.3 失败-设备不存在（Status 404）
7. 删除设备
- 7.1. 接口定义
- 7.2 请求示例
- 7.3 返回值
  - 7.3.1 成功（Status 200），返回body为空
8. 生成设备注册短链
- 8.1. 接口定义
- 8.2 请求示例
- 8.3 返回值
  - 8.3.1 成功（Status 200）
9. 禁用设备
- 9.1. 接口定义
- 9.2 请求示例
- 9.3 返回值
  - 9.3.1 成功（Status 200），无返回值
10. 启用设备
- 10.1. 接口定义
- 10.2 请求示例
- 10.3 返回值
  - 10.3.1 成功（Status 200），无返回值
11. 创建设备批量注册任务
- 11.1. 接口定义
  - 请求体(JSON)
- 11.2. 请求示例
- 11.3. 返回值
  - 11.3.1 成功（Status 200）
12. 查询设备批量注册任务执行状态
- 12.1. 接口定义
- 12.2. 请求示例
- 12.3. 返回示例
  - 12.3.1 返回数据说明
  - 12.3.2 成功（Status 200）
~~13. 动态注册（弃用，非安全方式）~~
- 13.1. 接口定义
- 13.2. 请求示例
- 13.3. 返回示例
  - 13.3.1. 成功（Status 200）
  - 13.3.2. 失败（Status 4xx）
14. 设置设备属性
- 14.1. 接口定义
  - 14.1.1 根据nodeId+deviceType+deviceName设置设备属性
  - 14.1.2 根据nodeId+deviceType+deviceName设置设备属性
- 请求体(JSON)
14.2 请求示例
14.3. 返回示例
- 14.3.1. 成功（Status 200），无返回体
- 14.3.2. 失败（Status 500），设备不在线
15. 设备方法调用
- 15.1. 接口定义
  - 15.1.1. 根据deviceId调用设备同步/异步方法
  - 15.1.2. 根据deviceType和deviceName调用设备同步/异步方法
- 请求体(JSON)
15.2 请求示例
15.3. 返回示例
- 15.3.1. 成功（Status 200），返回体格式由物模型方法出参定义
- 15.3.2. 失败（Status 500）, 设备离线
- 15.3.3. 失败（Status 500）, 非同步/异步方法
16. 一型一密动态注册
- 16.1. 接口定义
- 16.2 请求示例
- 16.3 返回示例
  - 16.3.1. 成功（Status 200），返回设备信息
  - 16.3.2. 失败（Status 4xx）
17.查询某产品下设备列表
- 17.1. 接口定义
- 17.2. 请求示例
- 17.3. 返回示例
  - 17.3.1. 成功（Status 200）
18.单个设备注册
- 18.1. 接口定义
  - 请求体(JSON)
    - ⚠️设备名称deviceName和设备别名deviceAlias需要满足如下格式要求：
18.2. 请求示例
18.3. 返回示例
- 18.3.1. 成功（Status 200）
- 18.3.2. 失败（Status 400）

1. 查询节点下的设备列表

1.1. 接口定义

GET /node/{nodeId}/{deviceType}/devices/meta?search={search}&status={status}&pageNo={pageNo}&pageSize={pageSize}

参数	是否必填	说明
nodeId	是	节点ID
deviceType	是	设备类型示例： - LEMO极简设备: LEMO - rfid读写器: rfid_reader - hfc_rfid读写器: hfc_rfid_reader
search	否	设备名称或设备id
status	否	为空时不过滤。设备状态，取值： - ONLINE：在线 - OFFLINE：离线 - UNACTIVE：未激活 - DISABLE：已禁用
pageNo	是	页码
pageSize	是	页大小，单页最大查询100条数据

1.2. 请求示例

GET '/node/118d5961484f8fd533c417a27e6c53fe/hfc_rfid_reader/devices/meta?pageNo=1&pageSize=10' -- header 'Token:002689b8-a50a-4f49-8c32-a463d6175446'

1.3. 返回值

1.3.1. 成功 (Status 200)

{
    "data":[
        {
            "deviceId":"58bfdacf0d9ef758dbaf9b3799a99abd",
            "deviceType":"LEMO",
            "deviceName":"shouzhi_test_device",
            "deviceAlias":"this is a alias",
            "groupId":"IOT_INNTER_TEST_PRE",
            "nodeId":"118d5961484f8fd533c417a27e6c53fe",
            "online":false,
            "activeTime":null
        },
        {
            "deviceId":"7f7bb1c80333aabd12d74e793df3055e",
            "deviceType":"LEMO",
            "deviceName":"test-device-id-123",
            "deviceAlias":null,
            "groupId":"IOT_INNTER_TEST_PRE",
            "nodeId":"118d5961484f8fd533c417a27e6c53fe",
            "online":false,
            "activeTime":null
        },
        {
            "deviceId":"8a09f108b4ae65b5a40d75d831dcab92",
            "deviceType":"LEMO",
            "deviceName":"device-name-123456789",
            "deviceAlias":"设备sdk测试设备",
            "groupId":"IOT_INNTER_TEST_PRE",
            "nodeId":"118d5961484f8fd533c417a27e6c53fe",
            "online":false,
            "activeTime":null
        },
        {
            "deviceId":"4045de190a683a39aaf0fa890790cbd9",
            "deviceType":"LEMO",
            "deviceName":"device-name-1111111",
            "deviceAlias":null,
            "groupId":"IOT_INNTER_TEST_PRE",
            "nodeId":"118d5961484f8fd533c417a27e6c53fe",
            "online":false,
            "activeTime":null
        },
        {
            "deviceId":"b6dec180fb85178be23275badc9eb0d8",
            "deviceType":"LEMO",
            "deviceName":"device-name-222222222",
            "deviceAlias":null,
            "groupId":"IOT_INNTER_TEST_PRE",
            "nodeId":"118d5961484f8fd533c417a27e6c53fe",
            "online":false,
            "activeTime":null
        },
        {
            "deviceId":"39e78c42b5c60e21152aa177b074760d",
            "deviceType":"LEMO",
            "deviceName":"test-device-01234567",
            "deviceAlias":null,
            "groupId":"IOT_INNTER_TEST_PRE",
            "nodeId":"118d5961484f8fd533c417a27e6c53fe",
            "online":false,
            "activeTime":null
        },
        {
            "deviceId":"e28bc3dacd7485b7a1c72e2ad0d7bccb",
            "deviceType":"LEMO",
            "deviceName":"7c:a7:b0:6a:8e:a2",
            "deviceAlias":"守之的测试设备",
            "groupId":"IOT_INNTER_TEST_PRE",
            "nodeId":"118d5961484f8fd533c417a27e6c53fe",
            "online":false,
            "activeTime":null
        },
        {
            "deviceId":"2c4b67cfad230601fa65d8a4d9facae6",
            "deviceType":"LEMO",
            "deviceName":"test-device-123",
            "deviceAlias":"测试设备",
            "groupId":"IOT_INNTER_TEST_PRE",
            "nodeId":"118d5961484f8fd533c417a27e6c53fe",
            "online":false,
            "activeTime":null
        },
        {
            "deviceId":"f1b7f708b129535829fe386d5ecbb2ef",
            "deviceType":"LEMO",
            "deviceName":"test-device-12345689",
            "deviceAlias":"mock device",
            "groupId":"IOT_INNTER_TEST_PRE",
            "nodeId":"118d5961484f8fd533c417a27e6c53fe",
            "online":false,
            "activeTime":null
        },
        {
            "deviceId":"db3c4f7d6c024f53eefb58453512c9f4",
            "deviceType":"LEMO",
            "deviceName":"b0:f8:93:8f:7f:6e",
            "deviceAlias":"ecs压测专用设备",
            "groupId":"IOT_INNTER_TEST_PRE",
            "nodeId":"118d5961484f8fd533c417a27e6c53fe",
            "online":false,
            "activeTime":null
        }
    ],
    "total":21,
    "totalPages":3
}

1.3.2. 失败-节点不存在 (Status 404)

Node not exists: 118d5961484f8fd533c417a27e6c53f1

2. 查询设备信息

2.1. 接口定义

GET /{deviceType}/device/{deviceName}/meta

参数	是否必填	说明
deviceType	是	设备类型
deviceName	是	设备名称

2.2. 请求示例

GET '/LEMO/device/58bfdacf0d9ef758dbaf9b3799a99abd/meta' -- header 'Token:002689b8-a50a-4f49-8c32-a463d6175446'

2.3. 返回值

2.3.1. 成功 (Status 200)

{
    "deviceId":"58bfdacf0d9ef758dbaf9b3799a99abd",
    "deviceType":"LEMO",
  "deviceName":"shouzhi_test_device",
  "deviceAlias":"this is a alias",
  "groupId":"IOT_INNTER_TEST_PRE",
  "nodeId":"118d5961484f8fd533c417a27e6c53fe",
  "online":false,
  "activeTime":null
}

2.3.2. 失败-设备不存在 (Status 404)

Device not exists. deviceType: LEMO, deviceName: shouzhi_test_device

3. 根据设备ID查询设备信息

3.1. 接口定义

GET /device/{deviceId}/meta

参数	是否必填	说明
deviceId	是	设备ID

3.2. 请求示例

GET '/device/58bfdacf0d9ef758dbaf9b3799a99abd/meta'

3.3. 返回值

3.3.1. 成功 (Status 200)

{
    "deviceId":"58bfdacf0d9ef758dbaf9b3799a99abd",
    "deviceType":"LEMO",
  "deviceName":"shouzhi_test_device",
  "deviceAlias":"this is a alias",
  "groupId":"IOT_INNTER_TEST_PRE",
  "nodeId":"118d5961484f8fd533c417a27e6c53fe",
  "online":false,
  "activeTime":null
}

3.3.2. 失败-设备不存在 (Status 404)

Device not exists: 58bfdacf0d9ef758dbaf9b3799a99abd

4. 查询设备属性

4.1. 接口定义

GET /node/{nodeId}/{deviceType}/device/{deviceName}/properties?propertyNames={propertyNames}

参数	是否必填	说明
nodeId	是	节点ID
deviceType	是	设备类型
deviceName	是	设备名称
propertyNames	否	为空时查询所有属性可以指定一个或多个属性名称，以英文逗号“,”隔开示例： language,timezone

4.2. 请求示例

GET '/node/118d5961484f8fd533c417a27e6c53fe/LEMO/device/7c:a7:b0:6a:8e:a2/properties'

4.3. 返回值

4.3.1. 成功 (Status 200)

{
    "otaVersion": {
        "value": "2.2.0.14",
        "time": 1631194662000
    },
    "wifiMac": {
        "value": "7c:a7:b0:6a:8e:a1\n",
        "time": 1631194662000
    },
    "sn": {
        "value": "H02001L10100160",
        "time": 1631194662000
    },
    "deviceInfo": {
        "value": {
            "deviceId": "66406dffd7de488cab0628335e43d946",
            "name": "LEMO_",
            "hardwareVersion": "H02001L10100160"
        },
        "time": 1631194662000
    }
}

4.3.2. 失败-设备不存在 (Status 404)

Device not exists. deviceType: LEMO, deviceName: 7c:a7:b0:6a:8e:a2

5. 根据设备ID查询设备属性

5.1. 接口定义

GET /device/{deviceId}/properties?propertyNames={propertyNames}

参数	是否必填	说明
deviceId	是	设备ID
propertyNames	否	为空时查询所有属性可以指定一个或多个属性名称，以英文逗号“,”隔开示例： language,timezone

5.2. 请求示例

GET '/device/66406dffd7de488cab0628335e43d946/properties'

5.3. 返回值

5.3.1. 成功 (Status 200)

{
    "otaVersion": {
        "value": "2.2.0.14",
        "time": 1631194662000
    },
    "wifiMac": {
        "value": "7c:a7:b0:6a:8e:a1\n",
        "time": 1631194662000
    },
    "sn": {
        "value": "H02001L10100160",
        "time": 1631194662000
    },
    "deviceInfo": {
        "value": {
            "deviceId": "66406dffd7de488cab0628335e43d946",
            "name": "LEMO_",
            "hardwareVersion": "H02001L10100160"
        },
        "time": 1631194662000
    }
}

5.3.2. 失败-设备不存在 (Status 404)

Device not exists: 66406dffd7de488cab0628335e43d946

6. 设置设备期望属性

6.1. 接口定义

16.1.1 根据nodeId+deviceType+deviceName设置设备期望属性

POST /node/{nodeId}/{deviceType}/device/{deviceName}/properties/desired

参数	是否必填	说明
nodeId	是	节点ID
deviceType	是	设备类型
deviceName	是	设备名称

16.1.1 根据deviceId设置设备期望属性

POST /device/{deviceId}/properties/desired

参数	是否必填	说明
deviceId	是	设备唯一ID

请求体(JSON)

需要设置的设备属性，支持设置多个属性。
设备属性是JSON格式，每个属性的具体结构为：Key:Value。
Key是属性名称，Value是属性值+属性上报时间的集合。

Value也为JSON格式，每个Value的具体结构为：

  {"value":"属性值","time":上报时间(毫秒时间戳)}<br />例如：

{
  "language": {
      "value": "GMT+8",
      "time": 1640831293770
  },
  "aoaSwitch": {
      "value": 1,
      "time": 1640831495419
  }
}

6.2 请求示例

POST '/node/6696d7a77ca996fe80eaef34509a9877/LEMO/device/0827768921be8183/properties'
--data '{"aoaSwitch":{"value":1,"time":1640831495419}}'

6.3 返回值

6.3.1 成功（Status 200），返回body为空

6.3.2 失败-未指定属性/非空属性值为空/物模型定义非法（Status 400）

// 未指定属性
Properties not specified
// 非空属性值为空
property 'timezone' is required
// 物模型定义非法
unsupported type: list

6.3.3 失败-设备不存在（Status 404）

Device not exists: {deviceId}

7. 删除设备

7.1. 接口定义

POST /device/{deviceId}/delete

参数	是否必填	说明
deviceId	是	设备ID

7.2 请求示例

POST '/device/66406dffd7de488cab0628335e43d946/delete'

7.3 返回值

7.3.1 成功（Status 200），返回body为空

8. 生成设备注册短链

8.1. 接口定义

POST /node/{nodeId}/{deviceType}/device/short-url?ttl={ttl}

参数	传参方式	是否必填	说明
nodeId	路径参数	是	节点id
deviceType	路径参数	是	设备类型
ttl	查询参数	是	短链有效期，单位：秒，范围3600 ～ 86400
propertyMap	JSON Body	否	预置属性（非必填）。生成设备注册短链时，允许为设备设置预置属性。一旦传入了预置属性，该接口生成的短链，会自动为设备设置预置属性。格式：预置属性是JSON格式，每个属性的具体结构为：Key:Value。 Key是属性在物模型定义中的identifier，Value是属性值。

8.2 请求示例

无需预置属性

POST '/node/1b747c8faf3c4021a3b66cf451fc5ed6/testWorkstation4/device/short-url?ttl=3600'

需要预置属性（请求短链进行注册设备时，会根据生成短链时的预置属性为设备设置属性）

curl --location --request 
POST '/node/d5623b012de447f3a710bea3bd3353e1/LEMO/device/short-url?ttl=3600'
--header 'Content-Type: application/json'
--data-raw '{
    "language": "zh_CN.UTF-8"
}'

8.3 返回值

8.3.1 成功（Status 200）

http://dev-devops.loginx.cainiao.test/s/3Q3FU0

POST方式请求上述返回值中的url（http://dev-devops.loginx.cainiao.test/s/3Q3FU0），即可实现设备注册，如下所示：

POST http://dev-devops.loginx.cainiao.test/s/3Q3FU0
--data {
    "deviceName": "21:01:20:11:49:13",
    "deviceAlias": "短链注册工作台设备",
    "properties": {}
}

9. 禁用设备

9.1. 接口定义

POST /device/{deviceId}/disable

参数	是否必填	说明
deviceId	是	设备id

9.2 请求示例

POST '/device/2f87d4d8d5e1b62f52cbd5c87fb4ba6e/disable'

9.3 返回值

9.3.1 成功（Status 200），无返回值

10. 启用设备

10.1. 接口定义

POST /device/{deviceId}/enable

参数	是否必填	说明
deviceId	是	设备id

10.2 请求示例

POST '/device/2f87d4d8d5e1b62f52cbd5c87fb4ba6e/enable'

10.3 返回值

10.3.1 成功（Status 200），无返回值

11. 创建设备批量注册任务

本接口调用返回的成功结果，仅表示批量注册的申请已经提交成功。实际的注册会有一个过程。请调用查询设备批量注册任务执行状态接口查看批量注册结果。

11.1. 接口定义

POST /node/{nodeId}/{deviceType}/device/batch-register-job

参数	是否必填	说明
nodeId	是	节点id，同一批预注册设备必须同属一个物流节点
deviceType	是	设备类型，同一批预注册设备必须同属一种设备类型

请求体(JSON)

需要设置的设备名称/别名，支持设置多个设备。格式如下：

[
    {
        "deviceName": "xxx01",
        "deviceAlias": "xxx01"
    },
    {
        "deviceName": "xxx02",
        "deviceAlias": "xxx02"
    }
]

⚠️设备名称和设备别名需满足格式规范。

11.2. 请求示例

POST '/node/a5d76108694f471ebe6036a60b0b1278/LEMO/device/batch-register'
--data-raw '[
    {
        "deviceName": "test_batch_register-02131600",
        "deviceAlias": ""
    },
    {
        "deviceName": "$test_batch_register-02131601",
        "deviceAlias": ""
    }
]'

11.3. 返回值

返回数据说明详见 13.3.1 返回数据说明

11.3.1 成功（Status 200）

IoT平台返回申请批次ID（applyId）以及批量注册记录（包括设备名称校验合法的设备集合originRegistrationDevices，以及设备名称校验非法的设备集合failedDeviceRegisterRecords）。 ⚠️注意：返回成功仅表示批量校验设备名称的申请已经提交成功。实际的校验是异步执行的，会有一个过程。

{
    "applyId": 373,
    "status": "CREATING",
    "deviceType": "LEMO",
    "nodeId": "52c2fe3b97ee49ba999f3b33582b5ad1",
    "originRegistrationDevices": [
        {
            "deviceId": "6644102d556e4cb2a7e8435be9b6a787",
            "deviceType": "LEMO",
            "deviceName": "test_batch_register-02131600",
            "deviceAlias": "test_batch_register_02131600",
            "groupId": "INNTER_TEST_PRE",
            "nodeId": "52c2fe3b97ee49ba999f3b33582b5ad1",
            "online": false,
            "clinkVersion": null,
            "activeTime": null
        }
    ],
    "successRegisteredDevices": null,
    "failedDeviceRegisterRecords": [
        {
            "deviceName": "$test_batch_register-02131601",
            "deviceAlias": "",
            "errorMessage": "device name must be 4 to 32 characters in length, and can contain letters, digits, hyphens (-), underscores (_), at signs (@), periods (.), and colons (:)"
        }
    ],
    "createTime": null,
    "updateTime": null
}

12. 查询设备批量注册任务执行状态

12.1. 接口定义

GET /device/batch-register/status?applyId={applyId}

参数	是否必填	说明
applyId	是	申请批次ID

12.2. 请求示例

/device/batch-register/status?applyId=371

12.3. 返回示例

12.3.1 返回数据说明

字段	说明
applyId	申请批次ID
status	申请单的处理状态和结果： CREATING // 设备批量创建任务执行中 CREATE_SUCCESS, �// 设备批量创建任务完成，全部成功或部分成功 CREATE_FAILED; // 设备批量创建任务完成，全部失败
deviceType	批量注册的设备类型
nodeId	节点id
originRegistrationDevices	接口传入的所有“设备名称(deviceName)合法”的待注册设备列表
successRegisteredDevices	注册成功的设备列表 - 当返回Status参数值为CREATE_SUCCESS时，返回创建成功的设备名称集合。 - 当返回Status参数值为CREATE_FAILED时，该参数为空数组。 - 当返回Status参数值为CREATING时，该参数为空。
failedDeviceRegisterRecords	“设备名称非法”或“注册失败”的设备列表（非空时包含设备信息（device �字段）和失败原因（errorMessage字段）） - 当返回Status参数值为CREATE_SUCCESS或CREATE_FAILED时，返回创建失败的设备名称及失败原因集合。 - 当返回Status参数值为CREATING时，返回由于“设备名称校验失败”导致注册失败的设备名称及失败原因集合，或返回空数组。

12.3.2 成功（Status 200）

{
    "applyId": 373,
    "status": "CREATE_SUCCESS",
    "deviceType": "LEMO",
    "nodeId": "52c2fe3b97ee49ba999f3b33582b5ad1",
    "originRegistrationDevices": [
        {
            "deviceId": "6644102d556e4cb2a7e8435be9b6a787",
            "deviceType": "LEMO",
            "deviceName": "test_batch_register-02131600",
            "deviceAlias": "test_batch_register_02131600",
            "groupId": "INNTER_TEST_PRE",
            "nodeId": "52c2fe3b97ee49ba999f3b33582b5ad1",
            "online": false,
            "clinkVersion": null,
            "activeTime": null
        }
    ],
    "successRegisteredDevices": [
        {
            "deviceId": "6644102d556e4cb2a7e8435be9b6a787",
            "deviceType": "LEMO",
            "deviceName": "test_batch_register-02131600",
            "deviceAlias": "test_batch_register_02131600",
            "groupId": "INNTER_TEST_PRE",
            "nodeId": "52c2fe3b97ee49ba999f3b33582b5ad1",
            "online": false,
            "clinkVersion": null,
            "activeTime": null
        }
    ],
    "failedDeviceRegisterRecords": [
        {
            "deviceName": "$test_batch_register-02131601",
            "deviceAlias": "",
            "errorMessage": "device name must be 4 to 32 characters in length, and can contain letters, digits, hyphens (-), underscores (_), at signs (@), periods (.), and colons (:)"
        }
    ],
    "createTime": 1644745281000,
    "updateTime": 1644745381000
}

13. 动态注册（弃用，非安全方式）

该接口将弃用，请使用新的动态注册接口

13.1. 接口定义

POST /{deviceType}/device/dynamic-register

13.2. 请求示例

/LEMO/device/dynamic-register
--data-raw '{
    "deviceName": "test_batch_register-02131600",
    "productSecret": "XXXXX5C51FA9FB1XXXXX8C3EC790F185XXXXX496C2A00C63XXXXX0344B3XXXXX"
}'

13.3. 返回示例

13.3.1. 成功（Status 200）

{
    "groupId": "INNTER_TEST_PRE",
    "deviceType": "LEMO",
    "deviceName": "test_batch_register-02131600",
    "deviceSecret": "CC234710B5EC413CD80CFF496FD67853B951C6F0A7CC5AE1B4ED91298E5C7DFC",
    "deviceId": "6644102d556e4cb2a7e8435be9b6a787",
    "nodeName": "木升测试节点",
    "nodeId": "52c2fe3b97ee49ba999f3b33582b5ad1",
    "nodeCode": "MSCSJD",
    "mqttBroker": {
        "address": [
            "tcp://11.161.91.194:8080"
        ],
        "version": "3.0",
        "cert": null
    },
    "httpServer": {
        "address": [
            "http://device-proxy.taobao.net"
        ],
        "version": "2.0",
        "cert": null
    },
    "mqttAddress": "tcp://11.161.91.194:8080"
}

13.3.2. 失败（Status 4xx）

// 设备类型不支持动态注册
400 Product: {deviceType} is not allowed to dynamically registered.

// 一型一密非法，动态注册失败
400 Invalid product secret, deny to register device dynamically.

// 设备不存在，请先进行设备预注册，或者查询批量注册任务执行状态
404 Device not found for nodeId: {nodeId}, deviceType: {deviceType}, deviceName: {deviceName}. Please pre-register the device first, or check the dynamical registration status.

14. 设置设备属性

本接口仅允许为在线设备设置属性值。如果设备不在线，则接口直接报错。

14.1. 接口定义

14.1.1 根据nodeId+deviceType+deviceName设置设备属性

POST /node/{nodeId}/{deviceType}/device/{deviceName}/properties

参数	是否必填	说明
nodeId	是	节点ID
deviceType	是	设备类型
deviceName	是	设备名称

14.1.2 根据nodeId+deviceType+deviceName设置设备属性

POST /device/{deviceId}/properties

参数	是否必填	说明
deviceId	是	设备唯一ID

请求体(JSON)

需要设置的设备属性，支持设置多个属性。
设备属性是JSON格式，每个属性的具体结构为：Key:Value。
Key是属性名称，Value是属性值
例如：

{
    "detailConfig": {
        "value": "{\"usbVideoDelayEnd\":5,\"junoEnable\":false,\"scaleComPort\":\"COM1\",\"scaleBaudRate\":19200,\"scaleModule\":1,\"isUsbVideoProxy\":false,\"directPrint\":false,\"cloudPrint\":\"cloud\",\"junoNetworkId\":\"88\",\"usbVideoSwitch\":false,\"storageId\":\"\"}",
        "time": 1644843410465
    }
}

14.2 请求示例

POST '/device/3d832b1b7c1359aab0549916757e125c/properties'
--data '{"detailConfig":{"value":"{\"usbVideoDelayEnd\":5,\"junoEnable\":false,\"scaleComPort\":\"COM1\",\"scaleBaudRate\":19200,\"scaleModule\":1,\"isUsbVideoProxy\":false,\"directPrint\":false,\"cloudPrint\":\"cloud\",\"junoNetworkId\":\"88\",\"usbVideoSwitch\":false,\"storageId\":\"\"}","time":1644843410465}}'

14.3. 返回示例

14.3.1. 成功（Status 200），无返回体

14.3.2. 失败（Status 500），设备不在线

errorCode:ALIYUN_LP_FAILED,errorMsg:The device is offline.

15. 设备方法调用

本接口仅允许为在线设备进行方法调用。如果设备不在线，则接口直接报错。

15.1. 接口定义

15.1.1. 根据deviceId调用设备同步/异步方法

同步方法调用：POST /device/{deviceId}/sync-method/{methodName} 异步方法调用：POST /device/{deviceId}/async-method/{methodName}

参数	是否必填	说明
deviceId	是	设备ID
methodName	是	物模型定义中的待调用方法identifier

15.1.2. 根据deviceType和deviceName调用设备同步/异步方法

同步方法调用：POST /{deviceType}/device/{deviceName}/sync-method/{methodName} 异步方法调用：POST /{deviceType}/device/{deviceName}/async-method/{methodName}

参数	是否必填	说明
deviceType	是	设备类型
deviceName	是	设备名称
methodName	是	物模型定义中的待调用方法identifier

请求体(JSON)

物模型方法定义中的方法入参。

如果物模型方法入参为空，例如："inputData": []，

则请求体传入空map:{};

如果物模型方法入参非空，例如：
```
"inputData":[{"identifier":"text","name":"text","dataType":{"type":"text","specs":{"length":2048}}}]
```
则请求体传入：{"text": "123"}
15.2 请求示例
```
POST '/device/516aad9a94ccab42b87d9f9bb0abae24/sync-method/speak'
--header 'content-type: application/json;charset=UTF-8'
--data '{"text":"123"}'
```
15.3. 返回示例
15.3.1. 成功（Status 200），返回体格式由物模型方法出参定义
15.3.2. 失败（Status 500）, 设备离线
```
errorCode:ALIYUN_LP_FAILED,errorMsg:The device is offline.
```
15.3.3. 失败（Status 500）, 非同步/异步方法

物模型定义中方法为同步（异步）方法，方法调用时发起了异步（同步）方法调用

errorCode:NOT_ASYNC_METHOD,errorMsg:this is not async method

16. 一型一密动态注册

16.1. 接口定义

POST /device/dynamic-register

参数	传参方式	是否必填	说明
registry	JSON Body	是	动态注册参数，JSON格式。每个参数的具体结构为：Key:Value。 Key是参数名，Value是参数值。Key区分大小写。动态注册必须包含Key为“deviceType”，“deviceName”，“sign”，“signMethod”四个参数，除上述四个必填参数外，允许自定义附加参数，附加参数将参数签名运算。其中： - “sign”签名计算规则如下： 1. 生成待签字符串：将所有提交给服务器的参数（sign、signMethod除外）按照非大小写敏感的字典序升序排序，然后将参数和值依次拼接（无拼接符号）。 1. 通过“signMethod”指定的加签算法，使用产品的productSecret，对待签字符串进行加签。 > 如果“deviceType”为“LEMO”， “deviceName”为“test”，则待签字符串为“deviceNametestdeviceTypeLEMO”。以HmacSHA256签名方法为例，签名“sign”计算示例如下：

sign = HexEncode(HmacSHA256(productSecret, deviceNametestdeviceTypeLEMO))。上式中，HexEncode表示以小写字母形式返回的Base16编码函数，HmacSHA256()表示基于HmacSHA256算法的哈希运算。

“signMethod”签名方法，目前支持HmacMD5、HmacSHA1、HmacSHA256。签名方法不区分大小写。
|

16.2 请求示例

POST '/device/dynamic-register'
--header 'Content-Type: application/json'
--data '{
    "deviceName": "test",
    "deviceType": "LEMO",
    "sign": "593287c5333f9b814a32b69d5e3acf717540241992ecdb3c17ebe980f929962d",
    "signMethod": "HmacSHA256"
}'

16.3 返回示例

16.3.1. 成功（Status 200），返回设备信息

{
    "groupId": "test_business_PRE",
    "deviceType": "LEMO",
    "deviceName": "test",
    "deviceSecret": "xxxxxx4c668fxxxxxxd571d762xxxxxx",
    "deviceId": "c9317ba4cfcfa60037fba1b745b7171c",
    "nodeName": "测试节点1",
    "nodeId": "a5d76108694f471ebe6036a60b0b1278",
    "nodeCode": "test_node1",
    "mqttBroker": {
        "address": [
            "tcp://1.2.3.4:8080"
        ],
        "version": "3.0",
        "cert": null
    },
    "httpServer": {
        "address": [
            "http://device-proxy.taobao.net"
        ],
        "version": "2.0",
        "cert": null
    },
    "mqttAddress": "tcp://1.2.3.4:8080"
}

16.3.2. 失败（Status 4xx）

// 设备类型不支持动态注册
400 Product: {deviceType} is not allowed to dynamically registered.

// 缺失必要的动态注册参数
400 deviceType/deviceName/sign/signMethod is absent.

// 不支持的签名方法
400 Algorithm {inputAlgorithm} not available, only support [HmacMD5, HmacSHA1, HmacSHA256].

// 验签失败
403 Failed to auth sign, deny to dynamically register device.

// 产品不存在
404 Product not exist for: {deviceType}

// 设备不存在，请先进行设备预注册，或者查询批量注册任务执行状态
404 Device not found for nodeId: {nodeId}, deviceType: {deviceType}, deviceName: {deviceName}. Please pre-register the device first, or check the dynamical registration status.

17.查询某产品下设备列表

17.1. 接口定义

GET /{deviceType}/devices?deviceNames=name1,name2,name3

参数	传参方式	是否必填	说明
deviceNames	查询参数	是	设备名称列表，最多允许传入50个设备名称，支持以”,”分隔符分割多个设备名称。以下两种传参方式等价：方式一：`?deviceNames=name1,name2,name3` 等价于方式二：`?deviceNames=name1&deviceNames=name2&deviceNames=name3`

⚠️注意：本接口仅会返回传入deviceNames中存在的设备。例如，查询参数中传入了三个设备名称，”name1”, “name2”, “name_not_exist” ，其中名称为”name_not_exist”的设备不存在，则接口返回的设备列表中将仅包含设备名称为”name1”, “name2”的设备信息。

17.2. 请求示例

GET '/LEMO/devices?deviceNames=test,short:url:register:test,08:00:27:91:5f:05'

17.3. 返回示例

17.3.1. 成功（Status 200）

[{
    "deviceId": "2f87d4d8d5e1b62f52cbd5c87fb4ba6e",
    "deviceType": "LEMO",
    "deviceName": "short:url:register:test",
    "deviceAlias": "短链注册测试设备",
    "groupId": "aliyu_business_PRE",
    "nodeId": "eb05f64cacd94a0e90b17b8ffd3e87c9",
    "clinkVersion": null,
    "activeTime": null,
    "lastOnlineTime": null,
    "productKey": "gppgjJgemdD",
    "status": "UNACTIVE"
}, {
    "deviceId": "256350ecc423edd667d2193c3ed14cb8",
    "deviceType": "LEMO",
    "deviceName": "08:00:27:91:5f:05",
    "deviceAlias": "测试1",
    "groupId": "aliyu_business_PRE",
    "nodeId": "a5d76108694f471ebe6036a60b0b1278",
    "clinkVersion": null,
    "activeTime": null,
    "lastOnlineTime": null,
    "productKey": "gppgjJgemdD",
    "status": "UNACTIVE"
}, {
    "deviceId": "c9317ba4cfcfa60037fba1b745b7171c",
    "deviceType": "LEMO",
    "deviceName": "test",
    "deviceAlias": "test",
    "groupId": "aliyu_business_PRE",
    "nodeId": "a5d76108694f471ebe6036a60b0b1278",
    "clinkVersion": null,
    "activeTime": null,
    "lastOnlineTime": null,
    "productKey": "gppgjJgemdD",
    "status": "OFFLINE"
}]

18.单个设备注册

18.1. 接口定义

POST /node/{nodeId}/{deviceType}/device

参数	是否必填	说明
nodeId	是	节点id，同一批预注册设备必须同属一个物流节点
deviceType	是	设备类型，同一批预注册设备必须同属一种设备类型

请求体(JSON)

需要设置的设备名称/别名。格式如下：

{
    "deviceName": "xxx",
    "deviceAlias": "xxx"
}

请求体中，deviceName为待注册的设备名称，deviceAlias为待注册的设备别名。

⚠️设备名称deviceName和设备别名deviceAlias需要满足如下格式要求：

deviceName长度为4~32个字符，可以包含英文字母、数字和特殊字符：短划线（-）、下划线（_）、at（@）、半角句号（.）、半角冒号（:）。

deviceAlias长度为4~64个字符，可包含中文汉字、英文字母、数字和下划线（_）。一个中文汉字算2个字符。

18.2. 请求示例

POST /node/a5d76108694f471ebe6036a60b0b1278/LEMO/device
--data-raw '{
  "deviceName": "device1",
  "deviceAlias": "device1别名"
}'

18.3. 返回示例

18.3.1. 成功（Status 200）

{
  "groupId": "aliyu_business_PRE",
  "deviceType": "LEMO",
  "productKey": "xxxgjJgexxx",
  "deviceName": "device1",
  "deviceSecret": "xxx",
  "deviceId": "xxxx6195c3acd39bcfa117b9860cxxxx",
  "iotId": "xxxxD81tGrEBtVU2MRwegpxxxx",
  "nodeName": "阿里云对接测试节点1",
  "nodeId": "a5d76108694f471ebe6036a60b0b1278",
  "nodeCode": "aliyun_node1",
  "mqttBroker": {
      "address": [
          "tcp://iot-010a09xr.mqtt.iothub.aliyuncs.com:1883"
      ]
  },
  "httpServer": {
      "address": [
          "http://11.161.37.234:80"
      ],
      "version": "2.0"
  },
  "mqttAddress": "tcp://iot-010a09xr.mqtt.iothub.aliyuncs.com:1883"
}

18.3.2. 失败（Status 400）

// 设备名称非法
400 device name must be 4 to 32 characters in length, and can contain letters, digits, hyphens (-), underscores (_), at signs (@), periods (.), and colons (:)

设备管理

1. 查询节点下的设备列表

1.1. 接口定义

1.2. 请求示例

1.3. 返回值

1.3.1. 成功 (Status 200)

1.3.2. 失败-节点不存在 (Status 404)

2. 查询设备信息

2.1. 接口定义

2.2. 请求示例

2.3. 返回值

2.3.1. 成功 (Status 200)

2.3.2. 失败-设备不存在 (Status 404)

3. 根据设备ID查询设备信息

3.1. 接口定义

3.2. 请求示例

3.3. 返回值

3.3.1. 成功 (Status 200)

3.3.2. 失败-设备不存在 (Status 404)

4. 查询设备属性

4.1. 接口定义

4.2. 请求示例

4.3. 返回值

4.3.1. 成功 (Status 200)

4.3.2. 失败-设备不存在 (Status 404)

5. 根据设备ID查询设备属性

5.1. 接口定义

5.2. 请求示例

5.3. 返回值

5.3.1. 成功 (Status 200)

5.3.2. 失败-设备不存在 (Status 404)

6. 设置设备期望属性

6.1. 接口定义

16.1.1 根据nodeId+deviceType+deviceName设置设备期望属性

16.1.1 根据deviceId设置设备期望属性

请求体(JSON)

6.2 请求示例

6.3 返回值

6.3.1 成功（Status 200），返回body为空

6.3.2 失败-未指定属性/非空属性值为空/物模型定义非法（Status 400）

6.3.3 失败-设备不存在（Status 404）

7. 删除设备

7.1. 接口定义

7.2 请求示例

7.3 返回值

7.3.1 成功（Status 200），返回body为空

8. 生成设备注册短链

8.1. 接口定义

8.2 请求示例

8.3 返回值

8.3.1 成功（Status 200）

9. 禁用设备

9.1. 接口定义

9.2 请求示例

9.3 返回值

9.3.1 成功（Status 200），无返回值

10. 启用设备

10.1. 接口定义

10.2 请求示例

10.3 返回值

10.3.1 成功（Status 200），无返回值

11. 创建设备批量注册任务

11.1. 接口定义

请求体(JSON)

11.2. 请求示例

11.3. 返回值

11.3.1 成功（Status 200）

12. 查询设备批量注册任务执行状态

12.1. 接口定义

12.2. 请求示例

12.3. 返回示例

12.3.1 返回数据说明

12.3.2 成功（Status 200）

13. 动态注册（弃用，非安全方式）

13.1. 接口定义

13.2. 请求示例

13.3. 返回示例

13.3.1. 成功（Status 200）

13.3.2. 失败（Status 4xx）

14. 设置设备属性