From 4a6d3e80d026861c97db7ac7dfd5fe4d0ec6a439 Mon Sep 17 00:00:00 2001 From: Kris Date: Tue, 14 May 2024 03:41:08 +0200 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96=E6=9B=B4=E6=96=B0=E4=B8=AD?= =?UTF-8?q?=E8=8B=B1=E6=96=87=E6=96=87=E6=A1=A3-=E7=AE=A1=E7=90=86?= =?UTF-8?q?=E9=9D=A2=E6=9D=BF-API?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en_US/guide/api.md | 142 +++++++++++++++++++++++++++++----------- docs/guide/api.md | 134 +++++++++++++++++++++++++++---------- 2 files changed, 204 insertions(+), 72 deletions(-) diff --git a/docs/en_US/guide/api.md b/docs/en_US/guide/api.md index 3ca29d5a..562d2246 100644 --- a/docs/en_US/guide/api.md +++ b/docs/en_US/guide/api.md @@ -1,34 +1,51 @@ -**Nezha Monitoring now supports querying the status information of the Agent in the Dashboard using the API** +--- +outline: deep +--- -## Create Token -API allows Token authentication method and Cookies authentication method -To create a new Token, after entering the admin panel, click on the avatar in the upper right corner and select "API Token" to enter the Token management page -Click "Add Token" and after customizing the notes, click "Add" -To delete a Token, please select the corresponding Token and click the delete icon on the right -::: warning -Token is the authentication tool of API, it is very important for your Dashboard's information security, please don't leak your Token to others +**Nezha Monitoring supports querying the status information of Agents using the API interface** + +## Creating a Token + +Nezha Monitoring's API interface allows for Token authentication and Cookies authentication. To create a new Token, go to the admin panel, click on the avatar in the top right corner, select "API Token," and enter the Token management page. Click "Add Token", add a custom note, and click "Add". + +To delete a Token, select the corresponding Token and click the delete icon on the right. + +::: warning +Tokens are the authentication credentials for the API interface. They are critical to the security of your Dashboard's information, so do not share your Token with others. ::: -## Authentication method -Token authentication method: -``` -Request Headers: +## Authentication Method + +Ensure the request header contains `Authorization: Token` for authentication. + +Token authentication method: +``` +Request Headers: Authorization: Token -``` -## How to use -::: warning -The negative timestamp in the example below is (0000-00-00) -It is currently used to indicate that the Agent has never reported since the Dashboard went live -However, it is not recommended to use positivity or negativity to determine the status -::: -::: tip -**The request method is `Get` and the return format is `JSON`.** -::: -+ Get a list of servers: `GET /api/v1/server/list?tag=` -query: tag (ServerTag means the group of servers, if this value is provided, only the servers in this group are queried) - -JSON Return Example: ``` + +## Usage Instructions + +::: warning +Negative timestamps in the following examples represent `0000-00-00`. This currently indicates that the Agent has never reported since the Dashboard went online, but it is not recommended to use the positive or negative value to determine the status. +::: + +::: tip +**The request method is `GET`, and the response format is `JSON`.** +::: + +### Get Server List + +Request: +``` +GET /api/v1/server/list?tag= +``` + +Parameters: +- `tag` (optional): ServerTag is the server group. Provide this parameter to query only servers in that group. + +Example response: +```json { "code": 0, "message": "success", @@ -53,14 +70,21 @@ JSON Return Example: } ] } -``` - -+ Get server details: `GET /api/v1/server/details?id=&tag=` -query: id (ServerID. Multiple IDs are separated by commas, provide this value to query the server corresponding to the ID, while ignoring the tag value) -query: tag (ServerTag, if this value is provided, only the servers in this group are queried) - -JSON Return Example: ``` + +### Get Server Details + +Request: +``` +GET /api/v1/server/details?id=&tag= +``` + +Parameters: +- `id` (optional): ServerID, multiple IDs separated by commas. Provide this parameter to query the server corresponding to that ID and ignore the `tag` parameter. +- `tag` (optional): ServerTag, provide this parameter to query only servers in that group. + +Example response: +```json { "code": 0, "message": "success", @@ -89,7 +113,7 @@ JSON Return Example: "Version": "" }, "status": { - "CPU": 17.330210772540017, + "CPU": 17.33, "MemUsed": 14013841408, "SwapUsed": 0, "DiskUsed": 2335048912896, @@ -98,9 +122,9 @@ JSON Return Example: "NetInSpeed": 10806, "NetOutSpeed": 5303, "Uptime": 331080, - "Load1": 5.23486328125, - "Load5": 4.873046875, - "Load15": 3.99267578125, + "Load1": 5.23, + "Load5": 4.87, + "Load15": 3.99, "TcpConnCount": 195, "UdpConnCount": 70, "ProcessCount": 437 @@ -148,3 +172,47 @@ JSON Return Example: ] } ``` + +## Usage Examples + +### Get All Server Information + +```python +import requests + +url = "http://your-dashboard/api/v1/server/list" +headers = { + "Authorization": "your_token" +} + +response = requests.get(url, headers=headers) +data = response.json() + +for server in data['result']: + print(f"Server Name: {server['name']}, Last Active: {server['last_active']}, IP: {server['valid_ip']}") +``` + +### Get Specific Server Details + +```python +import requests + +server_id = 1 # Replace with your server ID +url = f"http://your-dashboard/api/v1/server/details?id={server_id}" +headers = { + "Authorization": "your_token" +} + +response = requests.get(url, headers=headers) +data = response.json() + +server = data['result'][0] +print(f"Server Name: {server['name']}") +print(f"CPU Usage: {server['status']['CPU']}%") +print(f"Memory Used: {server['status']['MemUsed']} bytes") +print(f"Disk Used: {server['status']['DiskUsed']} bytes") +print(f"Network In Speed: {server['status']['NetInSpeed']} bytes/s") +print(f"Network Out Speed: {server['status']['NetOutSpeed']} bytes/s") +``` + +With the above example code, you can easily obtain and process server status information, enabling automated monitoring and management. \ No newline at end of file diff --git a/docs/guide/api.md b/docs/guide/api.md index 395bd195..c49b354c 100644 --- a/docs/guide/api.md +++ b/docs/guide/api.md @@ -2,37 +2,50 @@ outline: deep --- -**哪吒面板现在已经支持使用 API 接口查询面板中 Agent 的状态信息** +**哪吒监控支持使用 API 接口查询面板中 Agent 的状态信息** ## 创建 Token -哪吒面板的 API 接口允许使用 Token 认证与 Cookies 认证 -要新建一个 Token，在进入管理面板后，点击右上角的头像，选择 “API Token”，进入 Token 管理页面 -点击 “添加 Token”，自定义备注后，点击 “添加” -如需删除一个 Token，请选择相应的 Token，点击右侧的删除图标 -::: warning -Token 是 API 接口的鉴权工具，它对你的面板的信息安全非常重要，请不要泄漏你的 Token 给他人 + +哪吒面板的 API 接口允许使用 Token 认证与 Cookies 认证。要新建一个 Token，在进入管理面板后，点击右上角的头像，选择 “API Token”，进入 Token 管理页面。点击 “API Token”，自定义备注后，点击 “添加”。 + +如需删除一个 Token，请选择相应的 Token，点击右侧的删除图标。 + +::: warning +Token 是 API 接口的鉴权凭据，它对你的面板的信息安全非常重要，请不要泄漏你的 Token 给他人。 ::: ## 认证方式 -Token 认证方式： -``` -Request Headers: -Authorization: Token -``` -## 使用说明 -::: warning -下面示例中的负数时间戳为（0000-00-00） -目前表示 Dashboard 上线后该 Agent 从未汇报过 -但不建议用正负性判断状态 -::: -::: tip -**请求方式为 `Get`，返回格式为 `JSON`** -::: -+ 获取服务器列表：`GET /api/v1/server/list?tag=` -query: tag (ServerTag 是服务器的分组，提供此参数则仅查询该分组中的服务器) -JSON 返回示例： +确保在请求头中包含 `Authorization: Token` 进行身份认证。 + +Token 认证方式： +``` +Request Headers: +Authorization: Token ``` + +## 使用说明 + +::: warning +下面示例中的负数时间戳为（0000-00-00），目前表示 Dashboard 上线后该 Agent 从未汇报过，但不建议用正负性判断状态。 +::: + +::: tip +**请求方式为 `GET`，返回格式为 `JSON`** +::: + +### 获取服务器列表 + +请求： +``` +GET /api/v1/server/list?tag= +``` + +参数： +- `tag`（可选）：ServerTag 是服务器的分组，提供此参数则仅查询该分组中的服务器。 + +返回示例： +```json { "code": 0, "message": "success", @@ -57,14 +70,21 @@ JSON 返回示例： } ] } -``` - -+ 获取服务器详情：`GET /api/v1/server/details?id=&tag=` -query: id (ServerID 多个 ID 以逗号分隔，提供此参数则查询该 ID 对应的服务器，同时无视tag参数) -query: tag (ServerTag 提供此参数则仅查询该分组下的服务器) - -JSON 返回示例： ``` + +### 获取服务器详情 + +请求： +``` +GET /api/v1/server/details?id=&tag= +``` + +参数： +- `id`（可选）：ServerID，多个 ID 以逗号分隔，提供此参数则查询该 ID 对应的服务器，同时无视 `tag` 参数。 +- `tag`（可选）：ServerTag，提供此参数则仅查询该分组下的服务器。 + +返回示例： +```json { "code": 0, "message": "success", @@ -93,7 +113,7 @@ JSON 返回示例： "Version": "" }, "status": { - "CPU": 17.330210772540017, + "CPU": 17.33, "MemUsed": 14013841408, "SwapUsed": 0, "DiskUsed": 2335048912896, @@ -102,9 +122,9 @@ JSON 返回示例： "NetInSpeed": 10806, "NetOutSpeed": 5303, "Uptime": 331080, - "Load1": 5.23486328125, - "Load5": 4.873046875, - "Load15": 3.99267578125, + "Load1": 5.23, + "Load5": 4.87, + "Load15": 3.99, "TcpConnCount": 195, "UdpConnCount": 70, "ProcessCount": 437 @@ -152,3 +172,47 @@ JSON 返回示例： ] } ``` + +## 使用案例 + +### 获取所有服务器信息 + +```python +import requests + +url = "http://your-dashboard/api/v1/server/list" +headers = { + "Authorization": "your_token" +} + +response = requests.get(url, headers=headers) +data = response.json() + +for server in data['result']: + print(f"Server Name: {server['name']}, Last Active: {server['last_active']}, IP: {server['valid_ip']}") +``` + +### 获取特定服务器详情 + +```python +import requests + +server_id = 1 # 替换为你的服务器ID +url = f"http://your-dashboard/api/v1/server/details?id={server_id}" +headers = { + "Authorization": "your_token" +} + +response = requests.get(url, headers=headers) +data = response.json() + +server = data['result'][0] +print(f"Server Name: {server['name']}") +print(f"CPU Usage: {server['status']['CPU']}%") +print(f"Memory Used: {server['status']['MemUsed']} bytes") +print(f"Disk Used: {server['status']['DiskUsed']} bytes") +print(f"Network In Speed: {server['status']['NetInSpeed']} bytes/s") +print(f"Network Out Speed: {server['status']['NetOutSpeed']} bytes/s") +``` + +通过以上示例代码，可以轻松获取和处理服务器的状态信息，从而实现自动化监控和管理。 \ No newline at end of file