OpenAPI 規範

Telemetry 為記錄的 HTTP API 發布了機器可讀的 OpenAPI 3.1 規範。使用它來檢查端點合約、生成型別化客戶端作為起點、設定 API 瀏覽器或驗證 CI 中的範例請求。

該規範涵蓋：

• 使用 POST /log 進行結構化事件攝取；
• 同步SQL與POST /query；
• 非同步 JSON 和 Parquet 與 POST /query/async 和 GET /query/async/{job_id} 匯出；
• 資料表列表、模式檢查、保留、分割區列和刪除；
• 儀表板列表、建立、替換更新和刪除；
• 警示列表、建立、部分更新和刪除；
• 舊的行刪除端點，標記為已棄用。

下載規格書

curl -fsS https://telemetry.sh/openapi.json -o telemetry-openapi.json

該文件使用 https://api.telemetry.sh 作為其伺服器，並描述了兩種支援的授權標頭形式：

Authorization: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

不要將真正的 API 金鑰放入提交到儲存庫的規範、原始碼控制、生成的文件、範例、日誌或客戶端設定中。

驗證檔案

使用與 OpenAPI 3.1 相容的驗證器。例如，使用本地安裝的 Redocly CLI：

npx @redocly/cli lint telemetry-openapi.json

在 CI 中固定驗證器版本，以便工具升級不會意外更改發布行為。將有關不明確模式的警告視為審查專案，而不是自動抑制它們。

仔細生成客戶

生成的客戶端是腳手架，不能替代端點指南。生產使用前：

1. 驗證身分驗證和 API 金鑰範圍；
2. 設定連線和回應超時；
3. 僅重試具有有限指數退避和抖動的臨時故障；
4. 重試攝取時保留事件識別符號；
5. 對非同步查詢作業施加總輪詢截止時間；
6. 避免遙測失敗導致應用程式工作人員精疲力竭；
7. 分別檢視破壞性資料表和行刪除方法。

OpenAPI 架構有意將靈活的事件負載和查詢結果行保留為開放式，因為它們的欄位取決於您的事件契約和 SQL 投影。為應用程式中的這些有效負載生成域型別，而不是假設一種全域性事件形狀。

真實來源邊界

該規範反映了此儲存庫中的公共 API 文件。人類可讀的頁面仍然是操作指南、規範化行為、範例和故障模式的來源：

• 日誌API
• 查詢API
• 表格 API
• 儀表板API
• 警示 API
• 刪除API
• 速率限制和錯誤

特定於計劃的配額可能會發生變化，並且不會在規範中編碼為全域性數字費率。檢查產品和計費設定的當前帳戶限制。如果 OpenAPI 文件和即時 API 回應不一致，請捕獲最小安全複製並將其報告給 [email protected]；不要透過記錄憑據或私有負載來解決不匹配問題。