文档中心

托管 Prometheus

工作区数据写入和查询

通过 curl 方式访问 VMP Query 接口

本文面向需要通过 curl 接入 VMP 工作区的用户，支持 BasicAuth 鉴权方式，并提供可直接运行的 curl 完整调用示例。为您详细介绍查询接口的访问方法，覆盖即时查询、范围查询、时间序列查询、标签名与标签值查询操作，适用于接口联调、脚本集成及运维故障排查等场景。

前提条件

在开始调用前，请先准备以下信息：

已创建托管 Prometheus 工作区，并获取查询地址 query_url，详情请参见获取工作区地址。

BasicAuth 用户名/密码：用于使用 BasicAuth 鉴权访问工作区，为用户在工作区详情中配置的 BasicAuth 账号和密码。

准备依赖项及配置环境变量：

依赖项
用途
是否必需
curl
发送 HTTP 请求
是
base64
手动构造 BasicAuth 请求头时使用
否
jq
格式化 JSON 返回结果，便于查看
否

在 Shell 中配置环境变量：

export VMP_QUERY_URL="https://your-vmp-query-endpoint"
export VMP_USERNAME="your_basic_auth_username"
export VMP_PASSWORD="your_basic_auth_password"

查询示例

调用的接口说明与示例

接口路径	典型用途	说明
/api/v1/query	即时查询	查询某个时间点的当前值。
/api/v1/query_range	范围查询	查询一段时间内的趋势数据。
/api/v1/series	查询匹配的时间序列	适合确认某个指标或标签组合是否存在。
/api/v1/labels	查询标签名	适合排查当前工作区有哪些可用标签。
/api/v1/label/<name>/values	查询标签值	适合查看某个标签下已有的取值集合。

说明

调用查询接口后，返回结果中的关键字段说明如下：

status：表示请求是否成功。

data.resultType：表示结果类型。

data.result：包含实际的指标查询结果。

即时查询

# query 表示查询语句，可根据实际场景配置，替换为你的 PromQL​
# time 表示查询时间，可根据实际场景配置，格式为查询秒级时间戳或者 rfc3339 时间格式​
curl --location --user "$VMP_USERNAME:$VMP_PASSWORD" \​
  --get "$VMP_QUERY_URL/api/v1/query" \​
  --data-urlencode 'query=sum(up)' \​
  --data-urlencode "time=$(date +%s)" | jq​

范围查询

# query 表示查询语句，可根据实际场景配置，替换为你的 PromQL​
# start/end 表示查询时间范围，可根据实际场景配置，可根据实际场景配置，格式为查询秒级时间戳或者 rfc3339 时间格式​
# step 表示查询间隔，可根据实际场景配置，可根据实际场景配置，格式为时间段，例如 60s​
curl --location --user "$VMP_USERNAME:$VMP_PASSWORD" \​
  --get "$VMP_QUERY_URL/api/v1/query_range" \​
  --data-urlencode 'query=rate(prometheus_http_requests_total[5m])' \​
  --data-urlencode 'start=2025-10-09T07:25:00Z' \​
  --data-urlencode 'end=2025-10-09T07:55:00Z' \​
  --data-urlencode 'step=60s' | jq​

时间序列查询

# match[] 表示指定命中范围，可根据实际场景配置，格式为 series_selector 格式​
# start/end 表示查询时间范围，可根据实际场景配置，可根据实际场景配置，格式为查询秒级时间戳或者 rfc3339 时间格式​
curl --location --user "$VMP_USERNAME:$VMP_PASSWORD" \​
  --get "$VMP_QUERY_URL/api/v1/series" \​
  --data-urlencode 'match[]=up' \​
  --data-urlencode 'start=2025-10-09T06:55:00Z' \​
  --data-urlencode 'end=2025-10-09T07:55:00Z' | jq​

标签名查询

# match[] 表示指定命中范围，可根据实际场景配置，格式为 series_selector 格式​
# start/end 表示查询时间范围，可根据实际场景配置，可根据实际场景配置，格式为查询秒级时间戳或者 rfc3339 时间格式​
curl --location --user "$VMP_USERNAME:$VMP_PASSWORD" \​
  --get "$VMP_QUERY_URL/api/v1/labels" \​
  --data-urlencode 'match[]=up' \​
  --data-urlencode 'start=2025-10-09T06:55:00Z' \​
  --data-urlencode 'end=2025-10-09T07:55:00Z' | jq​

标签值查询

# 可根据实际场景替换为其他 label；此处以 instance 为例，查询其所有取值​
curl --location --user "$VMP_USERNAME:$VMP_PASSWORD" \​
  --get "$VMP_QUERY_URL/api/v1/label/instance/values" | jq​

常见问题与排查建议

Q1：鉴权失败，返回 401 / 403

可能原因：

BasicAuth 用户名或密码错误。

请求访问的工作区地址错误。

当前账号缺少目标工作区的访问权限。

排查建议：

使用查询命令验证连通性。

确认 --user "$VMP_USERNAME:$VMP_PASSWORD" 中的凭证是否正确。

Q2：查询成功但结果为空

可能原因：

PromQL 查询未匹配到相应数据。

查询时间范围过短。

写入的指标数据暂未同步至查询侧。

排查建议：

使用更简单的指标名。

将时间范围由最近 5 分钟扩大到最近 30 分钟。

等待 5～10 分钟再查询。

Q3：命令执行成功但输出难以阅读

可能原因：

返回结果为压缩后的单行 JSON。

本地未安装 jq 工具，无法对输出进行格式化。

排查建议：

在命令末尾追加 | jq。

若本地未安装 jq 工具，可暂时移除该命令，待确认接口可用后再行安装。

最近更新时间：2026.06.26 16:12:57

这个页面对您有帮助吗？

有用

无用

依赖项	用途	是否必需
curl	发送 HTTP 请求	是
base64	手动构造 BasicAuth 请求头时使用	否
jq	格式化 JSON 返回结果，便于查看	否