觀測云 OpenAPI 數(shù)據(jù)查詢接口最佳實踐

背景與價值

在云原生和微服務(wù)架構(gòu)日益普及的今天，可觀測性數(shù)據(jù)（日志、指標(biāo)、鏈路追蹤）呈爆炸式增長。觀測云 OpenAPI 數(shù)據(jù)查詢接口為開發(fā)者和運維團(tuán)隊提供了一種**編程化、自動化**獲取這些高價值數(shù)據(jù)的能力，例如：

- 自動化數(shù)據(jù)查詢：將觀測云數(shù)據(jù)集成到內(nèi)部系統(tǒng)或第三方平臺；

- 構(gòu)建自定義儀表盤：根據(jù)業(yè)務(wù)需求靈活展示監(jiān)控數(shù)據(jù)；

- 實現(xiàn)數(shù)據(jù)聯(lián)動：打通觀測云與企業(yè)內(nèi)部的數(shù)據(jù)分析流程；

- 批量數(shù)據(jù)處理：高效獲取大規(guī)模監(jiān)控數(shù)據(jù)進(jìn)行離線分析。

OpenAPI 概覽

觀測云將 OpenAPI 作為開放能力的關(guān)鍵構(gòu)成，支持工作空間配置和數(shù)據(jù)查詢，通過請求頭中附加的基于角色的 API Key 進(jìn)行認(rèn)證鑒權(quán)，默認(rèn)請求頻率限制為同一 API Key 每分鐘最多請求 20 次、同一工作空間每分鐘最多請求 200次。接入點和請求頭等請參考官方文檔 https://docs.guance.com/open-api/ 。

前置條件

- 創(chuàng)建 API Key：確保登錄用戶有所需的操作權(quán)限。登錄觀測云控制臺，點擊【管理】-【API Keys 管理】-【新建 Key】，填寫名稱與角色，本實踐僅使用數(shù)據(jù)查詢接口，因此使用內(nèi)置角色 “Read-only”。


- 調(diào)試 DQL：數(shù)據(jù)查詢接口通過傳入 DQL 查詢語句進(jìn)行查詢，建議在調(diào)用接口之前確認(rèn)查詢語句，完整語法請參考 https://docs.guance.com/dql/ ，可以在觀測云界面的查詢工具中進(jìn)行調(diào)試，點擊快捷方式 -【查詢工具】，選擇 DQL 查詢模式，支持語法校驗和自動補全：


數(shù)據(jù)查詢接口

基本信息

- 方法：POST

- 接口：/api/v1/df/query_data_v1

請求參數(shù)解析

queries，為 query 對象組成的列表，每個 query 對象中包含獨立的 DQL 語句，依次實現(xiàn)單次請求返回多組查詢結(jié)果，以下是單個 query 對象的關(guān)鍵參數(shù)：


場景解析

數(shù)據(jù)查詢場景和查詢方法分類如下，需根據(jù)不同的查詢類型合理配置查詢參數(shù)：


示例一：查詢指定 Span 的平均耗時（獲取聚合后的數(shù)據(jù)）

請求體，參數(shù)說明見注釋：

{

? ? "queries": [

? ? ? ? {

? ? ? ? ? ? "qtype": "dql",

? ? ? ? ? ? "query": {

? ? ? ? ? ? ? ? "q": "R::resource:(AVG(`duration`) AS `avg(duration)`) { `service` = 'demo' AND `resource` = 'GET /health' }",

? ? ? ? ? ? ? ? "interval": 60, // 查詢時間范圍內(nèi)每 60 秒聚合一個值

? ? ? ? ? ? ? ? "offset": 0,

? ? ? ? ? ? ? ? "limit": 500,

? ? ? ? ? ? ? ? "orderby": [

? ? ? ? ? ? ? ? ? ? {

? ? ? ? ? ? ? ? ? ? ? ? "time": "desc"

? ? ? ? ? ? ? ? ? ? }

? ? ? ? ? ? ? ? ],

? ? ? ? ? ? ? ? "timeRange": [

? ? ? ? ? ? ? ? ? ? 1774144800000, // 2026-03-22 10:00:00

? ? ? ? ? ? ? ? ? ? 1774145100000? // 2026-03-22 10:05:00

? ? ? ? ? ? ? ? ],

? ? ? ? ? ? ? ? "disable_sampling": true // 禁止聚合采樣

? ? ? ? ? ? }

? ? ? ? }

? ? ]

}

響應(yīng)體，僅包含重要返回數(shù)據(jù)及其注釋：

{

? ? "code": 200, // 狀態(tài)碼，與 HTTP 響應(yīng)碼保持一致，無錯誤時固定為 200

? ? "content": { // 接口響應(yīng)數(shù)據(jù)

? ? ? ? "data": [

? ? ? ? ? ? {

? ? ? ? ? ? ? ? // ...

? ? ? ? ? ? ? ? "next_cursor_time": -1,? // 下次請求的 cursor_time，因本次查詢?yōu)榫酆喜樵?，返回?-1

? ? ? ? ? ? ? ? "next_cursor_token": "", // 下次請求的 cursor_token，因本次查詢?yōu)榫酆喜樵?，返回為?/p>

? ? ? ? ? ? ? ? // ...

? ? ? ? ? ? ? ? "sample": 1,? ? ? ? ? ? // 采樣率，為 1 表示采樣率 100%，即未采樣

? ? ? ? ? ? ? ? // ...

? ? ? ? ? ? ? ? "series": [? ? ? ? ? ? ? // 數(shù)據(jù)查詢結(jié)果

? ? ? ? ? ? ? ? ? ? {

? ? ? ? ? ? ? ? ? ? ? ? "column_names": [

? ? ? ? ? ? ? ? ? ? ? ? ? ? "time",

? ? ? ? ? ? ? ? ? ? ? ? ? ? "avg(duration)"

? ? ? ? ? ? ? ? ? ? ? ? ],

? ? ? ? ? ? ? ? ? ? ? ? "columns": [

? ? ? ? ? ? ? ? ? ? ? ? ? ? "time",

? ? ? ? ? ? ? ? ? ? ? ? ? ? "avg(duration)"

? ? ? ? ? ? ? ? ? ? ? ? ],

? ? ? ? ? ? ? ? ? ? ? ? "units": [

? ? ? ? ? ? ? ? ? ? ? ? ? ? null,

? ? ? ? ? ? ? ? ? ? ? ? ? ? "time,ns"

? ? ? ? ? ? ? ? ? ? ? ? ],

? ? ? ? ? ? ? ? ? ? ? ? "values": [? ? ? ? ? ? ? ? // 每間隔一個 interval 秒聚合一個數(shù)據(jù)點

? ? ? ? ? ? ? ? ? ? ? ? ? ? [

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 1774145040000,? ? ? // 2026-03-22 10:04:00

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 1462101213.4054055

? ? ? ? ? ? ? ? ? ? ? ? ? ? ],

? ? ? ? ? ? ? ? ? ? ? ? ? ? [

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 1774144980000,? ? ? // 2026-03-22 10:03:00

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 520552891.31707317

? ? ? ? ? ? ? ? ? ? ? ? ? ? ],

? ? ? ? ? ? ? ? ? ? ? ? ? ? [

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 1774144920000,? ? ? // 2026-03-22 10:02:00

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 403010784

? ? ? ? ? ? ? ? ? ? ? ? ? ? ],

? ? ? ? ? ? ? ? ? ? ? ? ? ? [

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 1774144860000,? ? ? // 2026-03-22 10:01:00

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 496579998.11764705

? ? ? ? ? ? ? ? ? ? ? ? ? ? ],

? ? ? ? ? ? ? ? ? ? ? ? ? ? [

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 1774144800000,? ? ? // 2026-03-22 10:00:00

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 608395087.6444445

? ? ? ? ? ? ? ? ? ? ? ? ? ? ]

? ? ? ? ? ? ? ? ? ? ? ? ]

? ? ? ? ? ? ? ? ? ? }

? ? ? ? ? ? ? ? ],

? ? ? ? ? ? ? ? "window": 60000

? ? ? ? ? ? }

? ? ? ? ],

? ? ? ? // ...

? ? },

? ? "errorCode": "",? ? ? ? ? ? ? ? ? ? ? ? ? ? ? // 錯誤碼，空表示無錯誤

? ? "message": "",? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? // 錯誤信息

? ? "success": true,? ? ? ? ? ? ? ? ? ? ? ? ? ? ? // 接口調(diào)用狀態(tài)，為 true 時表示調(diào)用成功

? ? "traceId": "69bfdf42000000001ac3936f1436ac54" // 請求的跟蹤 ID

}

示例二：獲取指定類型的所有 Span（獲取原始數(shù)據(jù)）

采用分段查詢方式，請求體，參數(shù)說明見注釋：

{

? ? "queries": [

? ? ? ? {

? ? ? ? ? ? "qtype": "dql",

? ? ? ? ? ? "query": {

? ? ? ? ? ? ? ? "q": "R::resource:(`*`) { `service` = 'demo' AND `resource` = 'GET /health' }",

? ? ? ? ? ? ? ? "limit": 1,? ? ? ? ? ? ? ? ? // 分段大小為 1

? ? ? ? ? ? ? ? "cursor_time": 1774145100000, // 初始請求取 timeRange 中的結(jié)束時間，后續(xù)請求取響應(yīng)中的 next_cursor_time 的值

? ? ? ? ? ? ? ? "cursor_token": "",? ? ? ? ? // 初始請求取空值，后續(xù)請求取響應(yīng)中的 next_cursor_token 的值

? ? ? ? ? ? ? ? "orderby": [

? ? ? ? ? ? ? ? ? ? {

? ? ? ? ? ? ? ? ? ? ? ? "time": "desc"

? ? ? ? ? ? ? ? ? ? }

? ? ? ? ? ? ? ? ],

? ? ? ? ? ? ? ? "timeRange": [

? ? ? ? ? ? ? ? ? ? 1774144800000, // 2026-03-22 10:00:00

? ? ? ? ? ? ? ? ? ? 1774145100000? // 2026-03-22 10:05:00

? ? ? ? ? ? ? ? ]

? ? ? ? ? ? }

? ? ? ? }

? ? ]

}

響應(yīng)體，僅包含重要返回數(shù)據(jù)及其注釋：

{

? ? "code": 200, // 狀態(tài)碼，與 HTTP 響應(yīng)碼保持一致，無錯誤時固定為 200

? ? "content": { // 接口響應(yīng)數(shù)據(jù)

? ? ? ? "data": [

? ? ? ? ? ? {

? ? ? ? ? ? ? ? // ...

? ? ? ? ? ? ? ? "next_cursor_time": 1774145099284000, // 將值作為下次請求的 cursor_time

? ? ? ? ? ? ? ? "next_cursor_token": "1774145099284000000-R_1774145099284_d6vksl01so5nqftmhv20", // 將值作為下次請求的 cursor_token

? ? ? ? ? ? ? ? // ...

? ? ? ? ? ? ? ? "series": [ // 數(shù)據(jù)查詢結(jié)果

? ? ? ? ? ? ? ? ? ? {? ? ? // 將以單列的方式輸出一條原始數(shù)據(jù)的所有字段，示例響應(yīng)僅保留了 __block_id 字段，禁用單列模式時，列名、列值等分別作為一個單獨的數(shù)組

? ? ? ? ? ? ? ? ? ? ? ? "column_names": [

? ? ? ? ? ? ? ? ? ? ? ? ? ? "time",

? ? ? ? ? ? ? ? ? ? ? ? ? ? "__block_id"

? ? ? ? ? ? ? ? ? ? ? ? ],

? ? ? ? ? ? ? ? ? ? ? ? "columns": [

? ? ? ? ? ? ? ? ? ? ? ? ? ? "time",

? ? ? ? ? ? ? ? ? ? ? ? ? ? "__block_id"

? ? ? ? ? ? ? ? ? ? ? ? ],

? ? ? ? ? ? ? ? ? ? ? ? "units": [

? ? ? ? ? ? ? ? ? ? ? ? ? ? null,

? ? ? ? ? ? ? ? ? ? ? ? ? ? null

? ? ? ? ? ? ? ? ? ? ? ? ],

? ? ? ? ? ? ? ? ? ? ? ? "values": [

? ? ? ? ? ? ? ? ? ? ? ? ? ? [

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 1774145099284,

? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 2135893696351448600

? ? ? ? ? ? ? ? ? ? ? ? ? ? ]

? ? ? ? ? ? ? ? ? ? ? ? ]

? ? ? ? ? ? ? ? ? ? },

? ? ? ? ? ? ? ? ? ? // ...

? ? ? ? ? ? ? ? ],

? ? ? ? ? ? ? ? // ...

? ? ? ? ? ? }

? ? ? ? ],

? ? ? ? // ...

? ? },

? ? "errorCode": "",? ? ? ? ? ? ? ? ? ? ? ? ? ? ? // 錯誤碼，空表示無錯誤

? ? "message": "",? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? // 錯誤信息

? ? "success": true,? ? ? ? ? ? ? ? ? ? ? ? ? ? ? // 接口調(diào)用狀態(tài)，為 true 時表示調(diào)用成功

? ? "traceId": "69bfec720000000042c950e749998eff" // 請求的跟蹤 ID

}

最佳實踐

- 權(quán)限最小化：為不同的應(yīng)用場景（如報表系統(tǒng)、告警機(jī)器人）創(chuàng)建獨立的 API Key，并賦予最小必要權(quán)限；

- 避免觸發(fā) API 限流：一次請求中包含多條查詢語句，盡量在應(yīng)用層增加歷史數(shù)據(jù)緩存；

- 錯誤處理：必須對 API 返回的錯誤進(jìn)行處理，例如實現(xiàn)指數(shù)回退重試機(jī)制；

- 監(jiān)控請求 OpenAPI 的服務(wù)：確保相關(guān)業(yè)務(wù)健康運行；

- 在接口參數(shù)中設(shè)置聚合間隔和排序字段，而非在 DQL 中設(shè)置：DQL 支持以時間子句設(shè)置聚合間隔，但是 API 返回的點數(shù)受到優(yōu)先級規(guī)則限制，只有 interval 參數(shù)和時間子句中的間隔保持一致時才能獲得符合預(yù)期的結(jié)果，因此，建議使用 API 參數(shù)設(shè)置聚合間隔和排序方式，在其他場景中，如果 API 參數(shù)與 DQL 子句功能重復(fù)，仍然建議優(yōu)先使用 API 參數(shù)而非 DQL 子句，利于編碼且語義統(tǒng)一；

- 獲取原始數(shù)據(jù)時關(guān)閉單列模式，以減小響應(yīng)體的體積：請求時設(shè)置 disableMultipleField=false 即可關(guān)閉單列模式，注意，此時用于聚合查詢的 funcList 參數(shù)將失效。

總結(jié)

本文檔圍繞觀測云 OpenAPI 數(shù)據(jù)查詢接口展開，介紹了其在云原生可觀測場景下的應(yīng)用價值，說明了接口認(rèn)證、限流規(guī)則及創(chuàng)建 API Key、調(diào)試 DQL 語句等前置準(zhǔn)備，詳細(xì)解析了 `/api/v1/df/query_data_v1` 接口的請求參數(shù)，并通過聚合數(shù)據(jù)查詢、原始數(shù)據(jù)分段查詢兩個典型示例展示使用方法，最后給出權(quán)限、限流、錯誤處理等方面的最佳實踐，可幫助開發(fā)者快速接入并規(guī)范使用該接口實現(xiàn)監(jiān)控數(shù)據(jù)的程序化獲取與應(yīng)用。

?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時請結(jié)合常識與多方信息審慎甄別。
平臺聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點，簡書系信息發(fā)布平臺，僅提供信息存儲服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容