获取数据库指标
获取数据库的 CPU、RAM、网络、磁盘 I/O 和存储用量历史(GET /v2/databases/:database_id/metrics):24 小时内每 5 分钟一个数据点,Pro 和 Enterprise 套餐可获取 7 天、每小时一个数据点。
GET
/
v2
/
databases
/
{database_id}
/
metrics
获取数据库指标
curl --request GET \
--url https://api.squarecloud.app/v2/databases/{database_id}/metrics \
--header 'Authorization: <authorization>'import requests
url = "https://api.squarecloud.app/v2/databases/{database_id}/metrics"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://api.squarecloud.app/v2/databases/{database_id}/metrics', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.squarecloud.app/v2/databases/{database_id}/metrics",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.squarecloud.app/v2/databases/{database_id}/metrics"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.squarecloud.app/v2/databases/{database_id}/metrics")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.squarecloud.app/v2/databases/{database_id}/metrics")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"status": "success",
"response": [
{
"date": "2025-08-13T12:55:01.348Z",
"cpu": 0.45,
"ram": 111.27,
"net": [
16834,
126
],
"disk": [
7544832,
1310720
],
"storage": 11083776
},
{
"date": "2025-08-13T12:50:01.349Z",
"cpu": 0.45,
"ram": 111.22,
"net": [
16834,
126
],
"disk": [
7544832,
1179648
],
"storage": 11079680
},
{
"date": "2025-08-13T12:45:01.350Z",
"cpu": 0.58,
"ram": 111.36,
"net": [
16834,
126
],
"disk": [
7540736,
1048576
],
"storage": 11075584
},
{
"date": "2025-08-13T12:40:01.348Z",
"cpu": 0.43,
"ram": 118.44,
"net": [
16834,
126
],
"disk": [
7540736,
1048576
],
"storage": 11075584
}
]
}
需要具有
databases:read 权限范围的 API 密钥。
返回数据库过去 24 小时内的历史 CPU、RAM、网络、磁盘 I/O 和存储使用情况,每 5 分钟采样一次(最多 288 个数据点),按最新优先排列。在 Pro 和 Enterprise 套餐中,range=7d 会改为返回最近 7 天,每小时一个数据点,包含该小时的平均值和峰值。可用于绘制使用情况图表,或在调用编辑数据库之前判断数据库是否需要更多内存。
如果只需要单次当前读数而非时间序列,请使用获取数据库状态。响应按用户和数据库缓存 2.5 分钟(7d 为 10 分钟),该端点的速率限制为每用户每 5 秒 10 次请求,超出限制后会被短暂阻止。没有近期采样数据的数据库会返回空数组,而不是错误。
参数
string
必填
数据库的 ID。
string
默认值:"24h"
历史时间窗口:
24h(每 5 分钟一个数据点)或 7d(每小时一个数据点,Pro 和 Enterprise 套餐)。在其他套餐中,7d 会返回最近 24 小时,而不是报错。响应
string
指示调用是否成功。成功时为
success,否则为 error。array
响应的内容。
显示 属性
显示 属性
string
ISO 格式的日期。
number
当前 CPU 使用百分比。
number
当前 RAM 使用量,单位为 MB。
int[]
表示所用网络总量的数组。第一个为输入,第二个为输出。使用
range=7d 时,总量从最早的数据点开始累计,因此两个相邻数据点之差即为该小时的流量。int[]
表示磁盘 I/O 总量的数组,单位为字节。第一个为读取的字节数,第二个为写入的字节数。使用默认的
24h 时,总量从数据库启动时开始累计,因此两个相邻数据点之差即为该时间间隔内的 I/O;如果总量低于时间上的前一个数据点,说明数据库已重启。使用 range=7d 时,总量从最早的数据点开始累计,因此两个相邻数据点之差即为该小时的 I/O。24h 中没有读数的数据点(例如在此字段出现之前记录的数据点)为 null。number
该时间点数据库占用的磁盘空间,单位为字节(使用
range=7d 时为该小时结束时的值)。没有读数时为 null。可用它来跟踪磁盘使用量随时间的增长情况。number
仅在使用
range=7d 时返回:该小时内的最高 CPU 使用率百分比(cpu 为该小时的平均值)。number
仅在使用
range=7d 时返回:该小时内的最高 RAM 使用量,单位为 MB(ram 为该小时的平均值)。{
"status": "success",
"response": [
{
"date": "2025-08-13T12:55:01.348Z",
"cpu": 0.45,
"ram": 111.27,
"net": [
16834,
126
],
"disk": [
7544832,
1310720
],
"storage": 11083776
},
{
"date": "2025-08-13T12:50:01.349Z",
"cpu": 0.45,
"ram": 111.22,
"net": [
16834,
126
],
"disk": [
7544832,
1179648
],
"storage": 11079680
},
{
"date": "2025-08-13T12:45:01.350Z",
"cpu": 0.58,
"ram": 111.36,
"net": [
16834,
126
],
"disk": [
7540736,
1048576
],
"storage": 11075584
},
{
"date": "2025-08-13T12:40:01.348Z",
"cpu": 0.43,
"ram": 118.44,
"net": [
16834,
126
],
"disk": [
7540736,
1048576
],
"storage": 11075584
}
]
}
常见错误
| 代码 | HTTP | 说明 |
|---|---|---|
INVALID_PARAMETERS | 400 | range 不是 24h 或 7d。 |
DATABASE_NOT_FOUND | 404 | 数据库不存在,或不属于调用者。 |
相关内容
- CLI:
squarecloud db metrics - SDK:
api.databases.metrics()(JavaScript)、client.databases.metrics()(Python)、c.Databases.Metrics()(Go)
⌘I
获取数据库指标
curl --request GET \
--url https://api.squarecloud.app/v2/databases/{database_id}/metrics \
--header 'Authorization: <authorization>'import requests
url = "https://api.squarecloud.app/v2/databases/{database_id}/metrics"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://api.squarecloud.app/v2/databases/{database_id}/metrics', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.squarecloud.app/v2/databases/{database_id}/metrics",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.squarecloud.app/v2/databases/{database_id}/metrics"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.squarecloud.app/v2/databases/{database_id}/metrics")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.squarecloud.app/v2/databases/{database_id}/metrics")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"status": "success",
"response": [
{
"date": "2025-08-13T12:55:01.348Z",
"cpu": 0.45,
"ram": 111.27,
"net": [
16834,
126
],
"disk": [
7544832,
1310720
],
"storage": 11083776
},
{
"date": "2025-08-13T12:50:01.349Z",
"cpu": 0.45,
"ram": 111.22,
"net": [
16834,
126
],
"disk": [
7544832,
1179648
],
"storage": 11079680
},
{
"date": "2025-08-13T12:45:01.350Z",
"cpu": 0.58,
"ram": 111.36,
"net": [
16834,
126
],
"disk": [
7540736,
1048576
],
"storage": 11075584
},
{
"date": "2025-08-13T12:40:01.348Z",
"cpu": 0.43,
"ram": 118.44,
"net": [
16834,
126
],
"disk": [
7540736,
1048576
],
"storage": 11075584
}
]
}

