操作类接口

简介

夜莺对外的接口整体上分 2 类：

  • 用于页面功能，给 JavaScript 调用的，以 /api/n9e 打头
  • 用于第三方系统调用的，以 /v1/n9e 打头

/api/n9e 类接口

这类接口的认证走的是 jwt，需要获取 access_token，然后把 access_token 放到 Header 里。首先调用 /api/n9e/auth/login 接口来登录：

  1. # 调用登录接口拿到access_token和refresh_token记录下来，后面调用其他接口的时候会用到
  2. [root@10-255-0-34 ~]# curl -X POST 'http://localhost:18000/api/n9e/auth/login' -d '{"username": "root", "password": "root.2020"}'
  3. {"dat":{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NfdXVpZCI6ImIxNTcyMjgwLWZlNzAtNDhjZi1hNDQ3LWVlMjVhZmYwMjRhZCIsImF1dGhvcml6ZWQiOnRydWUsImV4cCI6MTYzNzgyMzA1OSwidXNlcl9pZGVudGl0eSI6IjEtcm9vdCJ9.nJ56Pc7qS5Ik_UaVmlNWu_QlABaBc4pZ_WkU45u2wWk","refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MzgzMzc4NTksInJlZnJlc2hfdXVpZCI6ImIxNTcyMjgwLWZlNzAtNDhjZi1hNDQ3LWVlMjVhZmYwMjRhZCsrMS1yb290IiwidXNlcl9pZGVudGl0eSI6IjEtcm9vdCJ9.JKsbfTYBCOOfR_oPsf496N9ml9yXbP7BHb4E8Yfnzbo","user":{"id":1,"username":"root","nickname":"超管","phone":"","email":"","portrait":"","roles":["Admin"],"contacts":{},"create_at":1637545881,"create_by":"system","update_at":1637546351,"update_by":"root","admin":true}},"err":""}

登录成功，后端返回了两个 token，access_token 和 refresh_token，程序要记录下来，后面有用，然后就可以调用普通接口了，调用的时候把 access_token 以 Bearer 的方式放到 Authorization 里：

  1. # access_token放到Authorization这个Header里，Bearer的验证方式
  2. [root@10-255-0-34 ~]# curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NfdXVpZCI6ImIxNTcyMjgwLWZlNzAtNDhjZi1hNDQ3LWVlMjVhZmYwMjRhZCIsImF1dGhvcml6ZWQiOnRydWUsImV4cCI6MTYzNzgyMzA1OSwidXNlcl9pZGVudGl0eSI6IjEtcm9vdCJ9.nJ56Pc7qS5Ik_UaVmlNWu_QlABaBc4pZ_WkU45u2wWk" 'http://localhost:18000/api/n9e/self/profile'
  3. {"dat":{"id":1,"username":"root","nickname":"超管","phone":"","email":"","portrait":"","roles":["Admin"],"contacts":{},"create_at":1637545881,"create_by":"system","update_at":1637546351,"update_by":"root","admin":true},"err":""}

access_token 有效期是 15 分钟，过期之后，可以调用 /api/n9e/auth/refresh 接口用 refresh_token 换一个新的 access_token，当然，也会顺道返回一个新的 refresh_token，举例：

  1. # 如果token过期了，后端会返回异常HTTP状态码，此时要调用refresh接口换取新的token
  2. [root@10-255-0-34 ~]# curl -X POST 'http://localhost:18000/api/n9e/auth/refresh' -d '{"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MzgzMzc4NTksInJlZnJlc2hfdXVpZCI6ImIxNTcyMjgwLWZlNzAtNDhjZi1hNDQ3LWVlMjVhZmYwMjRhZCsrMS1yb290IiwidXNlcl9pZGVudGl0eSI6IjEtcm9vdCJ9.JKsbfTYBCOOfR_oPsf496N9ml9yXbP7BHb4E8Yfnzbo"}'
  3. {"dat":{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NfdXVpZCI6IjAxMzkzYzkxLTk5MWItNGE0Yi04ODk2LTJhZGRjMDUwYjcxMCIsImF1dGhvcml6ZWQiOnRydWUsImV4cCI6MTYzNzgyMzMxOCwidXNlcl9pZGVudGl0eSI6IjEtcm9vdCJ9.2BeWyYfcnRi3qw69zecaaeFnPFUNAGsiPIZBBnd5lug","refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MzgzMzgxMTgsInJlZnJlc2hfdXVpZCI6IjAxMzkzYzkxLTk5MWItNGE0Yi04ODk2LTJhZGRjMDUwYjcxMCsrMS1yb290IiwidXNlcl9pZGVudGl0eSI6IjEtcm9vdCJ9.zFZaRYcJI6G5maSgDVF-jZzxQ3Tb5dybIqufJhBy034"},"err":""}

OK，如上就是认证方法。那 /api/n9e 打头的接口具体有哪些呢？打开 Chrome 开发者工具，看看页面上发起的请求就一目了然了，或者查阅夜莺的 router 文件 亦可知道全量接口。

/v1/n9e 类接口

这类接口其实又分成 2 小类：

  • 给 agent 使用，用于 agent 上报心跳信息或者接收监控数据，通常用于内网不加密钥认证
  • 给第三方调用的接口，通常会走密钥认证

这 2 类接口都是走的 BasicAuth 认证，通过配置文件里下面的部分来控制：

  1. [HTTP.APIForAgent]
  2. Enable = true 
  3. # [HTTP.APIForAgent.BasicAuth]
  4. # user001 = "ccc26da7b9aba533cbb263a36c07dcc5"
  6. [HTTP.APIForService]
  7. Enable = true 
  8. [HTTP.APIForService.BasicAuth]
  9. user001 = "ccc26da7b9aba533cbb263a36c07dcc5"

具体有哪些接口可以用呢：

  • 中心端 n9e 接收心跳的接口是 /v1/n9e/heartbeat n9e-edge 接收心跳的接口是 /v1/n9e/edge/heartbeat
  • 接收数据的接口在这里
  • 第三方调用的接口在这里