欢迎光临
我们一直在努力

CubePath GraphQL API 使用教程:统一查询VPS CPU、内存、磁盘及带宽监控数据

CubePath 于2026年10月23日通过官方邮件介绍旗下 GraphQL API 监控功能,支持用户通过统一接口查询 VPS、独立服务器、负载均衡器、Kubernetes 集群及其他云计算资源的运行指标。该功能已于2026年9月17日正式开放,此次邮件重点介绍如何使用 GraphQL API 构建自定义服务器监控面板和资源统计报表。

通过 GraphQL API,用户可以在一次请求中获取多台服务器的监控信息,包括 CPU使用率、内存占用、磁盘I/O、网络流量及月带宽使用量,不再需要为每项指标分别请求不同的监控接口。

值得注意的是,CubePath 原有的 REST 监控指标接口已于2026年9月23日退役,GraphQL API 成为新的监控数据查询接口。

CubePath 是一家提供 VPS、独立服务器、云计算及网络基础设施服务的海外主机商,支持通过管理控制台、REST API和GraphQL API管理或查询不同类型的云资源。

20261024 6adca376c7f11

官方网站:

https://cubepath.com/

GraphQL API官方文档:

https://cubepath.com/docs/products/settings/graphql-api

官方更新说明:

https://cubepath.com/changelog/graphql-api

一、CubePath GraphQL API支持哪些功能?

CubePath GraphQL API 是一个只读监控接口,主要用于获取服务器运行指标、资源健康状况及带宽统计。

资源类型 支持查询的数据
VPS云服务器 CPU、内存、磁盘I/O、网络流量、月带宽用量
VPS可用性组 平均CPU使用率、总内存、服务器数量
独立服务器 网络流量、数据包速率、带宽统计、BMC传感器
IP Transit 网络端口流量、数据包速率
负载均衡器 活跃连接数、新建连接速率、流量及带宽
NAT网关 入站与出站流量、月带宽用量
Kubernetes 集群健康状况、节点资源、Pod状态、API延迟
带宽资源统计 按位置、项目、产品或服务统计带宽

GraphQL 的主要优势是允许用户自行选择需要返回的字段,并在一个请求中获取多个资源的相关数据。

需要说明的是,GraphQL API 主要用于读取指标。创建、修改、删除 VPS 等资源管理操作,仍需通过 CubePath REST API 或其他受支持的管理接口完成。

二、如何创建CubePath API Token?

首先访问 CubePath 用户控制台:

https://my.cubepath.com/

登录后进入:

Organization → Tokens → Create Token

创建新的 API Token,并根据监控用途选择权限。

建议关闭 Full access,只开启必要的只读权限。

常见权限如下:

监控对象 API Token权限
VPS vps
独立服务器 baremetal
IP Transit network
负载均衡器 loadbalancer
NAT网关 nat_gateway
Kubernetes kubernetes

例如,如果只需要监控 VPS CPU、内存和流量,选择 vps 即可。

创建令牌时,还可以设置 Allowed IPs,将 Token 的访问来源限定为监控服务器的公网IP。

注意:API Token 创建后仅显示一次,建议立即妥善保存,不要公开在网页、GitHub仓库或服务器日志中。

三、GraphQL API接口地址与认证方式

CubePath GraphQL API 接口地址:

https://api.cubepath.com/graphql

请求方式:POST

Content-Type:application/json

官方支持两种认证方式:

方式一:Authorization Bearer

Authorization: Bearer YOUR_API_TOKEN

方式二:X-API-Key

X-API-Key: YOUR_API_TOKEN

其中 YOUR_API_TOKEN 需要替换为自己的访问令牌。

GraphQL API 虽然通过 POST 请求提交查询,但官方明确说明,使用 API Token 调用这个只读接口时,不需要额外添加 X-Requested-With 请求头。

四、使用curl查询VPS列表

Linux用户可以直接在服务器终端使用 curl 调用 GraphQL API。

首先创建环境变量,用于保存 API Token:

export CUBEPATH_API_TOKEN='YOUR_API_TOKEN'

随后执行:

curl -X POST /
  https://api.cubepath.com/graphql /
  -H "Content-Type: application/json" /
  -H "Authorization: Bearer $CUBEPATH_API_TOKEN" /
  -d '{"query":"{ vpsList { id name } }"}'

该查询会返回当前账户有权限访问的 VPS 列表。

其中:

  • id:VPS服务器唯一ID。
  • name:服务器名称。
  • vpsList:查询VPS列表的GraphQL字段。

记录对应的 VPS ID,后续即可通过该 ID 查询服务器监控数据。

官方规定,vpsList 单次最多返回200台服务器。如果账户中存在大量服务器,需要根据实际支持的查询条件规划数据获取方式。

五、查询VPS CPU、内存和月流量

获得 VPS ID 后,可以进一步查询服务器最近6小时的CPU和内存监控记录。

GraphQL查询示例如下:

query Overview($id: ID!) {
  vps(id: $id) {
    name
    metrics(
      range: H6
      metrics: [CPU_USAGE, MEMORY_USAGE]
    ) {
      step
      series {
        name
        unit
        points {
          ts
          value
        }
      }
    }
    bandwidthUsage {
      inBytes
      outBytes
      totalBytes
    }
  }
}

上述查询主要包括:

  • CPU_USAGE:CPU使用率。
  • MEMORY_USAGE:内存使用率。
  • H6:最近6小时的监控数据。
  • step:采样间隔,单位为秒。
  • ts:Unix时间戳,采用UTC时间。
  • value:对应时间点的监控数值。
  • inBytes:进入服务器的流量字节数。
  • outBytes:离开服务器的流量字节数。
  • totalBytes:总流量字节数。

直接使用curl执行

下面提供包含服务器ID变量的完整请求示例。

curl -X POST /
  https://api.cubepath.com/graphql /
  -H "Content-Type: application/json" /
  -H "Authorization: Bearer $CUBEPATH_API_TOKEN" /
  -d '{
    "query": "query($id: ID!) { vps(id: $id) { name metrics(range: H6, metrics: [CPU_USAGE, MEMORY_USAGE]) { step series { name unit points { ts value } } } bandwidthUsage { inBytes outBytes totalBytes } } }",
    "variables": {
      "id": "1234"
    }
  }'

其中1234只是示例ID,实际使用时需要替换为自己账户中的 VPS ID。

成功执行后,接口会返回 JSON 数据。

例如,官方文档中的 CPU 监控数据示例包含:

{
  "name": "cpu_usage",
  "unit": "RATIO",
  "points": [
    {
      "ts": 1759406400,
      "value": 0.42
    }
  ]
}

这里的0.42代表42%的CPU使用率。

需要注意,不同监控指标的数据单位可能不同。只有 unit 为 RATIO 的比例数据才应按比例转换为百分比;字节、速率、温度等指标应按照其各自的单位处理。

CubePath 也支持磁盘I/O及网络使用情况查询。开发者可以通过已认证的 GraphQL Schema Introspection 查询接口的可用类型、字段和指标枚举,避免直接猜测参数名称。

六、GraphQL API支持哪些时间范围?

CubePath GraphQL API 提供8种常用的监控时间窗口。

参数 监控范围
H1 最近1小时
H3 最近3小时
H6 最近6小时
H12 最近12小时
H24 最近24小时
D3 最近3天
D7 最近7天
D30 最近30天

未设置 range 参数时,默认查询最近1小时的数据。

不同时间范围对应不同的采样粒度。例如,查询最近1小时可能返回较高密度的监控数据,而查询最近30天则会使用更大的时间聚合间隔。

官方介绍,30天监控图表通常只返回约300个数据点,从而减少响应体积。

因此,排查短时间内的CPU异常或网络流量波动时,建议选择H1、H3等较短时间范围;制作长期运行趋势报表时,可以选择D7或D30。

七、如何查询指定月份的服务器流量?

CubePath GraphQL API 支持使用 bandwidthUsage 查询指定月份的流量消耗情况。

例如:

query MonthlyUsage($id: ID!) {
  vps(id: $id) {
    name
    bandwidthUsage(month: "2026-09") {
      inBytes
      outBytes
      totalBytes
    }
  }
}

这里的2026-09代表查询2026年9月的月度流量。

如果不提供 month 参数,接口默认查询当前月份截至查询时的流量。

月份必须采用 YYYY-MM 格式,并按UTC自然月统计。

对于需要管理多台VPS的用户,可以定期获取月流量数据,结合套餐配额建立带宽用量报表。不过,具体流量配额及超额计费规则仍需以对应产品说明为准。

八、GraphQL API的请求限制

CubePath 官方公布了接口频率、查询规模和复杂度限制。

限制类型 官方限制
单Token请求频率 每分钟600次
单次数据点数量 约24,000个
最大查询深度 6层
最大别名数量 15个
最大查询Token数 2,000
VPS列表单次返回 最多200台
批量操作数组 不支持

需要注意,GraphQL 在一次请求中可以包含多个资源字段,但并不支持通过批量操作数组提交多个独立操作。

当请求频率超过限制时,接口可能返回 HTTP 429,并通过 Retry-After 响应头提示重试等待时间。

对于监控程序,建议按照实际需求设置合理采集周期,并实现缓存及错误重试机制。

常见错误代码

错误代码 说明
UNAUTHENTICATED Token缺失或无效
FORBIDDEN 缺少权限或资源被暂停
NOT_FOUND 资源不存在或不属于当前组织
BAD_USER_INPUT 参数错误或查询字段无效
METRICS_UNAVAILABLE 监控指标暂时不可用
QUERY_TOO_COMPLEX 查询复杂度超出限制

特别需要注意,GraphQL 请求即使返回 HTTP 200,也不一定代表所有字段查询成功。

部分字段失败时,响应可能同时包含 data 和 errors。因此,开发监控程序时不仅需要检查HTTP状态码,还应检查返回JSON中的 errors 字段。

对于临时不可用的监控数据,应保留其异常或未知状态,避免将缺失数据直接当作CPU使用率为0或流量为0。

九、如何将CubePath监控数据接入Grafana?

Grafana 是常见的服务器监控及数据可视化平台,可以用于展示CPU、内存、磁盘和网络流量等时序指标。

CubePath GraphQL API 支持通过标准接口读取监控数据,因此可以配合 Grafana 或其他可视化工具构建自定义面板。

基本接入流程如下:

  1. 登录CubePath控制台,创建具有只读权限的API Token。
  2. 使用curl或自建程序调用GraphQL接口。
  3. 查询目标VPS的CPU、内存、磁盘和网络指标。
  4. 提取返回数据中的时间戳、数值及单位。
  5. 将监控数据写入Grafana支持的时序数据库,或通过兼容插件查询。
  6. 在Grafana中配置CPU、内存、网络及月流量统计图表。
  7. 根据需要设置监控阈值和异常告警。

例如,可以创建CPU使用率、内存使用率、网络流量、磁盘I/O以及月流量统计等面板,集中查看多台VPS的运行情况。

需要说明的是,CubePath并未在上述GraphQL API文档中提供开箱即用的Grafana原生数据源。用户需要根据所选Grafana版本、数据源插件和数据存储方案,自行完成认证、数据转换及面板配置。

对于不希望自行开发监控程序的用户,CubePath控制台也提供服务器运行指标图表及相关云监控告警功能。

总结

CubePath GraphQL API 为VPS、独立服务器、Kubernetes、负载均衡及其他云基础设施提供统一的只读监控数据查询入口。

相较于分别请求多个监控接口,GraphQL 可以一次查询多个资源,只返回所需字段,适合多服务器集中管理、带宽统计、基础设施监控及自定义报表等场景。

对于普通VPS用户,可以通过curl快速获取CPU、内存及月流量信息;对于需要长期统计的运维人员,则可以结合Grafana或自建监控面板,实现更灵活的服务器资源可视化管理。

未经允许不得转载:主机之家测评 » CubePath GraphQL API 使用教程:统一查询VPS CPU、内存、磁盘及带宽监控数据