- 快猫星云Flashcat

如何使用 API 呼叫夜鶯（Nightingale）介面：頁面操作類 API（Token 認證）與資料推送類 API（OpenTSDB、Open-Falcon、Prometheus Remote Write）。

本文介紹如何使用 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。

create api 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 介面。比如：

Chrome Network

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，避免安全風險。