TMX Access™ 服务平台 2.0 编程接口指南

ThingsMatrix 平台提供一整套 API 用户和平台进行可编程化交互。通常第三方应用或脚本会使用到这些接口。如果你之前未曾接触过这些 API 接口,请仔细阅读一下所有章节。

参考

认证鉴权

  • 接口支持两种认证方式:
    • APIKey。密钥通过用户界面生成和重置。
    • Bearer Authentication. 令牌可以通过用户登入接口获取。该接口需要提供用户名和 MD5 加密密码。
  • 鉴权是通过登入用户的账户和角色单独定义。

使用指南

以下章节描述的 API 接口的基本功能和格式。

分页

部分 APIs 采用分页方式来限制响应消息包的大小。分页请求是通过 page 和 size 查询参数指定提交, 缺省返回为第一页,每页 10 行。

例如:

?page=1&size=100

返回的分页信息封装在整个 JSON 体内的分页信息表内,例如:

{
  "totalElements": "integer (int32)",
  "last": "boolean",
  "totalPages": "integer (int32)",
  "number": "integer (int32)",
  "size": "integer (int32)"
}

排序

部分 APIs 支持通过指定字段进行排序。排序是通过 sort 查询参数指定提交。排序可以支持升序和降序,用"asc"或者“desc”做相应的指定。缺省排序为降序。

例如:

?sort=name desc
?sort=property1,property2 asc
?sort=property1 asc&sort=property2 desc
?sort=attributes.location desc

过滤

部分 APIs 支持通过指定字段进行过滤。排序是通过查询参数指定提交。部分 APIs 并支持扩展属性字段查询。

例如:

?name=test
?name=test&attributes=location US
?attributes=location US,zipcode 12345&tags=tag1&page=1&size=10&sort=attributes.location desc'

响应

大多数 APIs 的响应消息都是具有固定返回格式并带有返回状态码。

{
  "code": "integer (int32)",
  "data": "object",
  "msg": "string"
}

返回码列表

Table of Return Code:

Code Description
-1 unknown error
0 success
9999 fail
10001 request body check error %s
10002 %s service invocation failed
10003 duplicate record
10004 edit failed
10005 query failed
10006 delete failed
10007 %s non-existent
10008 %s %s do not match
10009 %s resource access failed
10010 %s cannot be empty
10011 %s isn't allowed to be edited
10012 %s isn't allowed to be deleted
10013 %s alreayd exists
10014 request body parse error
10015 unique field %s already exists
10016 %s ready only
10017 invalid id %s
10018 invalid sn %s
10019 table %s does not exist
14101 invalid token
14102 token parse failed
14103 not authorized
14201 username or password incorrect
14202 user forbidden
14203 company forbidden
14401 invalid or non-existent equipment
14402 "[%s/%s] relationship is not allowed to be modified
14403 "[%s] and device are related
14404 "[%s] model are inconsistent
14405 group does not have elements
14406 [%s] and group are related
14407 invalid operations (same group)
14408 no data available for %s-%s
14410 groupId:[%s] does not match model:[%s]
14501 the protocol does not support this instruction

使用样例

这一章节包含几个简单的创建设备组,设备,查询设备的样例。

例 1: 查询设备列表

请求格式:

$ curl -X POST --header 'Content-Type: application/json' \
> --header 'Accept: application/json' \
> --header 'Authorization: Bearer <Token>' \
> -d '{ "compositeStatus": 1}' \
> 'https://demo.thingsmatrix.io/api/device/list'

响应数据格式:

{
  "code":0,
  "msg":"success",
  "data":{
    "content":[{
      "id":"049f0fe6de9b764c",
      "sn":"12345688922",
      "imei":null,
      "iccid":"234567890975",
      "iccidOverwrite":1,
      "sensorSn":"66180800800143",
      "sensorOverwrite":1,
      "onlineStatus":1,
      "status":1,
      "attributes":{},
      "tags":[],
      "description":null,
      "creator":"admin",
      "createTime":"2019-06-27 12:26:14",
      "updator":null,
      "updateTime":null,
      "model":{
        "id":"bf37ac4057e022a8",
        "name":"TMA01",
        "vendor":"ThingsMatrix",
        "type":1,
        "description":"Logistics Tracker (2G, LTE)",
        "creator":"admin",
        "createTime":"2019-06-25 03:55:27",
        "updator":"",
        "updateTime":null
      },
      "group":{
        "id":"5c6e62336a837fdd",
        "name":"tma01_g1",
        "description":"",
        "creator":"admin",
        "createTime":"2019-06-25 04:15:58",
        "updator":null,
        "updateTime":null
      }
    },{
      "id":"e7d8acd99ae7c7a6",
      "sn":"12345688821",
      ...
    },...,{
      ...
    }],
    "pageable":{
      "sort":{
        "sorted":true,
        "unsorted":false
      },
      "offset":0,
      "pageSize":15,
      "pageNumber":0,
      "paged":true,
      "unpaged":false
    },
    "totalPages":5,
    "totalElements":67,
    "last":false,
    "first":true,
    "sort":{
      "sorted":true,
      "unsorted":false
    },
    "size":15,
    "number":0,
    "numberOfElements":15
  }
}

例 2: 查询单台设备的具体信息

请求格式:

$ curl -X GET --header 'Accept: application/json' \
> --header 'Authorization: Bearer <token>' \
> 'https://demo.thingsmatrix.io/api/device/sn/12345688922'

响应数据格式:

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": "049f0fe6de9b764c",
    "sn": "12345688922",
    "imei": null,
    "iccid": "234567890975",
    "iccidOverwrite": 1,
    "sensorSn": "66180800800143",
    "sensorOverwrite": 1,
    "onlineStatus": 1,
    "status": 1,
    "attributes": {},
    "tags": [],
    "description": null,
    "creator": "admin",
    "createTime": "2019-06-27 12:26:14",
    "updator": null,
    "updateTime": null,
    "model": {
      "id": "bf37ac4057e022a8",
      "name": "TMA01",
      "vendor": "ThingsMatrix",
      "type": 1,
      "description": "Logistics Tracker (2G, LTE)",
      "creator": "admin",
      "createTime": "2019-06-25 03:55:27",
      "updator": "",
      "updateTime": null
    },
    "group": {
      "id": "5c6e62336a837fdd",
      "name": "tma01_g1",
      "description": "",
      "creator": "admin",
      "createTime": "2019-06-25 04:15:58",
      "updator": null,
      "updateTime": null
    }
  }
}
Last updated: 2021/4/23 下午5:34:46