cURL 和 HTTP API 範例
使用 cURL 驗證 API 金鑰、重現 SDK 請求、自動化伺服器端指令碼或在嚮應用程式新增檢測之前測試故障處理。
設定金鑰
在不記錄秘密值的 shell 中匯出金鑰：
export TELEMETRY_API_KEY="YOUR_API_KEY"
使用寫入範圍的金鑰進行攝取，使用單獨的讀取範圍的金鑰進行查詢或報告。禁用圍繞擴充套件金鑰的命令的 shell 追蹤。
傳送一個事件
curl --fail-with-body \
--connect-timeout 2 \
--max-time 10 \
--request POST \
"https://api.telemetry.sh/log" \
--header "Authorization: ${TELEMETRY_API_KEY}" \
--header "Content-Type: application/json" \
--data @- <<'JSON'
{
"table": "api_request_completed",
"data": {
"event_id": "evt_request_101",
"route_template": "/api/projects/:id",
"method": "GET",
"status_code": 200,
"status": "success",
"latency_ms": 184
}
}
JSON
Telemetry 新增 timestamp_utc。請勿將 API 金鑰、授權標頭、cookie、原始請求正文、提示或私人客戶內容作為事件欄位傳送。
傳送相容批次
data 欄位可以是一個陣列：
curl --fail-with-body \
--connect-timeout 2 \
--max-time 10 \
--request POST \
"https://api.telemetry.sh/log" \
--header "Authorization: ${TELEMETRY_API_KEY}" \
--header "Content-Type: application/json" \
--data @- <<'JSON'
{
"table": "job_completed",
"data": [
{
"event_id": "evt_job_101",
"job_name": "invoice_sync",
"status": "success",
"duration_ms": 912
},
{
"event_id": "evt_job_102",
"job_name": "invoice_sync",
"status": "failed",
"duration_ms": 2401,
"error_type": "provider_timeout"
}
]
}
JSON
保持每個物件與相同的資料表模式相容。批次處理可減少請求開銷，但會增加受一個失敗請求影響的事件數量。
執行SQL
curl --fail-with-body \
--connect-timeout 2 \
--max-time 30 \
--request POST \
"https://api.telemetry.sh/query" \
--header "Authorization: ${TELEMETRY_API_KEY}" \
--header "Content-Type: application/json" \
--data @- <<'JSON'
{
"query": "SELECT route_template, COUNT(*) AS requests, ROUND(AVG(latency_ms), 0) AS avg_latency_ms FROM api_request_completed WHERE timestamp_utc >= now() - INTERVAL '24 hours' GROUP BY route_template ORDER BY requests DESC;"
}
JSON
檢查 status、data 和 key_order 欄位，而不是假設結果非空。
匯出更大的結果
啟動非同步 Parquet 匯出：
curl --fail-with-body \
--connect-timeout 2 \
--max-time 30 \
--request POST \
"https://api.telemetry.sh/query/async" \
--header "Authorization: ${TELEMETRY_API_KEY}" \
--header "Content-Type: application/json" \
--data @- <<'JSON'
{
"query": "SELECT * FROM api_request_completed WHERE timestamp_utc >= now() - INTERVAL '30 days' ORDER BY timestamp_utc DESC;",
"format": "parquet"
}
JSON
使用相同的授權標頭輪詢返回的 status_url。當query_status為completed時，下載download_url。停止對 failed 進行輪詢並強制執行總體截止日期。
檢查並驗證資料表
curl --fail-with-body \
--connect-timeout 2 \
--max-time 10 \
"https://api.telemetry.sh/tables/api_request_completed/schema" \
--header "Authorization: ${TELEMETRY_API_KEY}"
傳送綜合的成功、失敗、重試和超時情況。在建立儀表板或警示之前，請確認欄位型別、單位、UTC 時間戳以及是否缺少敏感欄位。
重試和退出程式碼策略
--fail-with-body 對於 HTTP 故障退出非零，同時保留回應正文以進行安全診斷。
- 退出
6：DNS解析失敗。 - 退出
7：連線失敗。 28：超時退出；伺服器可能已接受也可能未接受該請求。- HTTP
400：修復請求；不要重試不變。 - HTTP
401或403：替換憑證或更正其範圍。 - HTTP
429、502、503或504：使用有界指數退避和抖動重試。
將相同的 event_id 重複用於邏輯事件。在未考慮重複交付的情況下，請勿使用 --retry-all-errors。