API
本文介绍如何使用 API 调用夜莺监控（Nightingale）的接口，主要是两类接口，一类是页面操作类，就是使用 API 模仿用户在页面上的操作，另一类是数据推送类，比如自己的程序采集了监控数据，想要推送给夜莺。
页面操作类
页面操作类的 API 主要是模拟用户在页面上的操作，比如创建告警规则、修改机器标签、修改机器备注、调整机器归属的业务组等。所有用户在页面上的操作，都可以使用 API 完成，您可以通过这些接口来实现自动化操作。
显然，要调用 API 需要有两个前提：
- 搞定认证
- 了解有哪些接口，各个接口有哪些参数
搞定认证
这里直接讲解 v8.0.0-beta.5 以上版本的认证方式，即个人中心 token 方式，这是最简单的方式。
1. 修改配置文件
修改夜莺的配置文件 etc/config.toml，确保配置了 HTTP.TokenAuth，并且设置了 Enable = true，如下所示：
...
[HTTP.RSA]
OpenRSA = false
[HTTP.TokenAuth]
Enable = true
[DB]
...
2. 获取 Token
登录夜莺监控，进入右上角头像，进入个人信息页面，点击 “Token 管理” 那个 Tab，然后点击“创建 Token”，随便起个名字，就可以得到一个 Token。
3. 使用 Token
在调用 API 的时候，需要在 HTTP 请求的 Header 中添加 X-User-Token 字段，值为你刚才创建的 Token。用 cURL 命令调用 API 的示例：
curl -s -X GET "http://<NIGHTINGALE_HOST><API_URL_PATH>" \
-H "X-User-Token: <YOUR_TOKEN>" \
-H "Content-Type: application/json"
我们测试一下获取个人信息的接口：
curl -s -H "X-User-Token: e6897d32-c237-4d27-a0fc-786345b682ea" -H "Content-Type: application/json" 'http://10.99.1.106:8003/api/n9e/self/profile' | python3 -m json.tool
{
"dat": {
"id": 1,
"username": "root",
"nickname": "Root",
"phone": "",
"email": "qinxiaohui@flashcat.cloud",
"portrait": "/image/avatar1.png",
"roles": [
"Admin"
],
"contacts": {
"wecomid": "qinxiaohui"
},
"maintainer": 0,
"create_at": 1733229739,
"create_by": "system",
"update_at": 1749811268,
"update_by": "root",
"belong": "",
"admin": true,
"user_groups": null,
"busi_groups": null,
"last_active_time": 1749811088
},
"err": ""
}
如上，正常返回了内容，表示成功。如果你要写程序调用 API，需要校验：
- 夜莺返回的 HTTP 状态码是否为 200，如果状态码不是 200，表示请求失败，此时可以把 Response Body 打印出来，查看具体的错误信息。
- 如果状态码是 200，Response Body 肯定是 JSON，此时还要校验 JSON 数据中
err字段是否为空，如果不为空就是有问题的。
了解有哪些接口
查看接口文档，或者，直接使用 Chrome 打开夜莺的页面，按 F12 打开开发者工具，切换到 Network 标签页，然后在页面上操作，比如创建一个告警规则，或者修改机器标签等。你会看到 Network 中有很多 API 请求，这些就是夜莺的 API 接口。比如：
- Headers 下面可以看到 Request Method 和 URL
- Response 下面可以看到返回的内容
上面的接口没有任何 Query string 参数，如果有 Query string 参数，通常会在 URL 中显示。另外，如果是 POST 请求，就需要研究 Request Body 的格式了，届时会出现一个 Payload 的 Tab，在 Payload 下面可以看到 Request Body 的内容格式。
这种方式比接口文档要好多了，接口文档经常忘记更新，而且不同版本的差异经常忘记说明，而通过查看 Chrome 的这种方式，那信息绝对是 100% 准确的，有哪些接口，有哪些参数，一目了然，每个运维、后端研发都应该懂得这种方式。
数据推送类
自己的程序暴露监控数据，通常有两个手段，一个是埋入 Prometheus SDK，暴露 /metrics 接口，然后用 Prometheus 或 Categraf 来抓取（称为 PULL 模式），另一个是直接调用夜莺的 API 接口，推送监控数据（称为 PUSH 模式），夜莺支持多种数据接收的接口，包括 OpenTSDB、Open-Falcon、PrometheusRemoteWrite、Datadog 等协议。
推送样例
以 OpenTSDB 协议为例，夜莺接口路径是 /opentsdb/put，HTTP Method 是 POST，Request Body 里放置你要上报的监控数据，格式样例如下：
[
{
"metric": "cpu_usage_idle",
"timestamp": 1637732157,
"tags": {
"cpu": "cpu-total",
"ident": "c3-ceph01.bj"
},
"value": 30.5
},
{
"metric": "cpu_usage_util",
"timestamp": 1637732157,
"tags": {
"cpu": "cpu-total",
"ident": "c3-ceph01.bj"
},
"value": 69.5
}
]
显然，JSON 最外层是个数组，如果只上报一条监控数据，也可以不要外面的中括号，直接把对象结构上报：
{
"metric": "cpu_usage_idle",
"timestamp": 1637732157,
"tags": {
"cpu": "cpu-total",
"ident": "c3-ceph01.bj"
},
"value": 30.5
}
服务端会看第一个字符是否是 [，来判断上报的是数组，还是单个对象，自动做相应的 Decode。如果觉得上报的内容太过占用带宽，也可以在你的程序里对 Request Body 做 gzip 压缩，同时在 HTTP Header 里带上 Content-Encoding: gzip 的 Header。
各个字段的含义可以 Google 一下或者询问 GPT，关键字是 “OpenTSDB 数据格式里各个字段的含义”。这里我稍作说明：
- metric: 监控指标的名称，通常是一个英文单词，多个单词用下划线连接，比如
cpu_usage_idle - timestamp: 时间戳，单位是秒，表示监控数据的采集时间
- tags: 标签，通常是一个 map 结构，key 是标签名，value 是标签值，用于描述指标的各类维度信息或元信息
- value: 监控数据的值，通常是一个数字，表示指标的数值
🟢 注意 ident 这个标签，ident 是 identity 的缩写，表示设备的唯一标识，如果标签中有 ident 标签，n9e 就认为这个监控数据是来自某个机器的，会自动获取 ident 的 value，注册到夜莺的机器列表里。
其他常用的接口路径：
/openfalcon/push: Open-Falcon 数据接收接口/prometheus/v1/write: Prometheus Remote Write 数据接收接口
如何认证
如果你的夜莺暴露在公网，那所有人都可以推监控数据给你，这显然是不安全的。所以我们建议：
- 不要把夜莺暴露在公网
- 如果实在要暴露在公网，要用 HTTPS 协议，同时开启 Basic Auth 认证
如何开启 Basic Auth 认证呢？在 etc/config.toml 中配置：
[HTTP.APIForAgent]
Enable = true
[HTTP.APIForAgent.BasicAuth]
user001 = "Pa55word01"
user002 = "Pa55word02"
你自己的程序调用夜莺的接口上报监控数据，此时你的程序就相当于一个 agent 的角色，所以就是跟 HTTP.APIForAgent 这块的配置相关。
HTTP.APIForAgent下面的 Enable 首先要设置为 true，才会启用相关接口，否则你调用那些上报数据的接口都会报 404 Not Found 错误。HTTP.APIForAgent.BasicAuth下面的配置是用户名和密码，格式是username = "password"，你可以设置多个用户，这些用户的认证方式是 Basic Auth。如果HTTP.APIForAgent.BasicAuth下面一个用户也没有配置，那么就表示不需要认证，任何人都可以推送数据。
🔴 注意：跟
HTTP.APIForAgent紧挨着的还有一个HTTP.APIForService配置段，用于提供一些接口给 n9e-edge 使用，即夜莺的边缘机房部署模式，如果你没有用到 n9e-edge，一定要把HTTP.APIForService给 Disable 掉，即HTTP.APIForService下面的 Enable 设置为 false，避免安全风险。
