本文面向需要通过 curl 接入 VMP 工作区的用户，支持 BasicAuth 鉴权方式，并提供可直接运行的 curl 完整调用示例。为您详细介绍查询接口的访问方法，覆盖即时查询、范围查询、时间序列查询、标签名与标签值查询操作，适用于接口联调、脚本集成及运维故障排查等场景。 ## 前提条件在开始调用前，请先准备以下信息： * 已创建托管 Prometheus 工作区，并获取**查询地址 query_url**，详情请参见 [获取工作区地址](https://www.volcengine.com/docs/6731/106506?lang=zh)。 * BasicAuth 用户名/密码 **：** 用于使用 BasicAuth 鉴权访问工作区，为用户在工作区详情中配置的 BasicAuth 账号和密码。 * 准备依赖项及配置环境变量： |**依赖项** |**用途** |**是否必需** | |---|---|---| |curl |发送 HTTP 请求 |是 | |base64 |手动构造 BasicAuth 请求头时使用 |否 | |jq |格式化 JSON 返回结果，便于查看 |否 | 在 Shell 中配置环境变量： ```Bash 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//values |查询标签值 |适合查看某个标签下已有的取值集合。 |

说明

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

status：表示请求是否成功。

data.resultType：表示结果类型。

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

### 即时查询 ```Bash # 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 ``` ### 范围查询 ```Bash # 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 ``` ### 时间序列查询 ```Bash # 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 ``` ### 标签名查询 ```Bash # 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 ``` ### 标签值查询 ```Bash # 可根据实际场景替换为其他 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 工具，可暂时移除该命令，待确认接口可用后再行安装。