Skip to main content

平台接口客户端

介绍​

平台客户端 SDK 用于访问平台接口，提供了平台接口的 Go 实现, 可以很方便实现第三方系统与平台的集成。平台客户端 SDK 中包括常用的 租户管理、项目管理、 用户管理、角色管理、工作表及数据管理、系统变量(数据字典)、报警管理 等接口, 并且不断在丰富和完善中。

使用方式​

1. 在项目中安装SDK​

go get github.com/air-iot/api-client-go/v4

2. 在需要调用平台接口创建客户端​

在引入客户端 SDK 后. 示例代码如下:

clientEtcd, err := clientv3.New(clientv3.Config{
    Endpoints:   []string{"127.0.0.1:2379"},
    DialTimeout: time.Second * time.Duration(60),
    DialOptions: []grpc.DialOption{grpc.WithBlock()},
    Username:    "用户名",
    Password:    "密码",
})
if err != nil {
    log.Fatal(err)
}

cli, clean, err := api_client_go.NewClient(clientEtcd, config.Config{
    EtcdConfig: "/airiot/config/dev.json",
    Metadata:   map[string]string{"env": "aliyun"},
    Services: map[string]config.Service{
    },
})
info

关于如何创建ak、sk

查询构造器​

客户端接口中的很多查询接口, 其结构比较复杂.

查询参数的整体结构如下所示:

{
  "project": {},
  "filter": {},
  "sort": {},
  "limit": 30,
  "skip": 20,
  "withCount": true
}

字段说明如下:

  • project 查询请求需要返回的字段列表. 例如: {"id": 1, "name": 1, "address": {"city": 1}}. key 为字段名, value 为 1 或 对象. 如果为为一级字段需要设置为 1 例如: {"id": 1, "name": 1}, 如果要返回嵌套对象内的字段, 则需要设置为 Map, 例如: {"address": {"city": 1}}
  • filter 查询条件, 如果没有添加任何条件则查询全部数据. key 为字段名, value 为过滤的值或逻辑运算符, 例如: {"name": "Tom", "age": {"$gt": 20, "$lt": 30}}.
  • sort 排序条件, key 为字段名, value 为 1 表示升序, -1 表示降序, 例如: {"age": 1, "name": -1}.
  • limit 查询结果的最大数量, 可用于分页查询或限制返回的记录数量.
  • skip 查询结果的偏移量, 即忽略前 N 记录, 可用于分页查询.
  • withCount 是否返回符合条件的记录总数, 如果为 true 则会在查询结果记录数量会保存在响应对象 ResponseDTO<T> 中的 count 字段.
info

注意事项

  1. 如果查询条件需要使用逻辑或, 可以在 filter 中添加 $or 字段, 其值为 {k:v} 结构与 filter 一致, 任一条件成立时表示记录匹配.
  2. 如果同一字段存在多个逻辑条件, 则需要将多个条件放在一个 对象 中, 例如: {"age": {"$gt": 20, "$lt": 30}}, 表示查询 20 < age < 30 的记录. :::

逻辑运算符​

符号说明示例
$not不相等, 与 SQL 中的 <> 作用相同{"age": {"$not": 18}}
$in在指定列表内, 与 SQL 中的 in 作用相同{"id": {"$in": [1,3,4]}}
$nin不在指定列表内, 与 SQL 中的 not in 作用相同{"id": {"$nin": [1,3,4]}}
$gt大于指定的值, 与 SQL 中的 > 作用相同{"age": {"$gt": 18}}
$gte大于等于指定的值, 与 SQL 中的 >= 作用相同{"age": {"$gte": 18}}
$lt小于指定的值, 与 SQL 中的 < 作用相同{"age": {"$lt": 18}}
$lte小于等于指定的值, 与 SQL 中的 <= 作用相同{"age": {"$lte": 18}}
$regex正则匹配, 与 SQL 中的 like 相似{"name": {"$regex": "张"}}