驗證事件寫入與資料表結構
API 接受請求後，還需要確認事件是否真的寫入。在更多路由、背景工作或服務加入事件紀錄前，先檢查產生的資料表與紀錄。
此頁面假設您從 傳送您的第一個結構化事件 傳送了模擬 telemetry_quickstart 事件。
使用匿名 anon_… 金鑰？跳至下方的透過 API 驗證。同一金鑰可在首次傳送後 24 小時內讀取事件。要使用團隊介面，請建立帳戶並保留試用。在其他瀏覽器中註冊前，選擇**已有匿名 API 金鑰？**並輸入金鑰。
找到資料表
開啟您的 Telemetry 團隊，選擇 Tables，然後開啟 telemetry_quickstart。如果該資料表不存在：
- 確認 API 請求回傳成功回應。
- 確認金鑰屬於目標團隊並且具有寫入權限。
- 檢查正規化後的確切資料表名。
- 使用新的模擬
request_id重試一次。 - 變更結構前，請先參考 事件寫入疑難排解。
避免在沒有新識別碼的情況下重複傳送同一事件；重試可能會使以後的計數變得不明確。
檢查自動推斷的資料表結構
模擬 API 範例應產生類似以下內容的欄位：
| 欄位 | 預期資料型別 | 檢查項目 |
|---|---|---|
timestamp_utc |
時間戳記 | 一致產生並以 UTC 儲存 |
route_template |
文字 | 使用固定格式的路由範本，而不是完整 URL |
status_code |
整數 | 可以支援數值比較 |
latency_ms |
數值 | 統一使用毫秒 |
status |
文字 | 使用少量且有明確定義的狀態值 |
request_id |
文字 | 串聯相關事件，不包含機密資訊 |
如果重要欄位的型別錯誤，先修正產生事件的程式，再大量傳送正式環境的資料。同一欄位從數值變成任意文字，可能影響已儲存的 SQL 查詢與圖表。
檢查指定紀錄
使用 Samples 或 Table 檢視並找到 request_id = req_demo_001。確認：
- 紀錄屬於預期的環境與版本。
latency_ms是184，而不是0.184或184000。- 路由不包含真實報表或帳戶的識別碼。
- 不包含授權標頭、cookie、請求本文、機密資訊、提示詞或客戶的私人內容。
- 產生的時間符合傳送時段。
找到預期紀錄，代表這次測試符合事件資料規格；這不是效能基準，也不能代表正式環境的資料分佈。
透過 API 驗證
執行以下 API 檢查時，請在可信任的伺服器或本機終端機使用具有讀取權限的金鑰。Ingest only 金鑰只能傳送事件，不能列出資料表、查看結構或執行查詢。不要把具有讀取權限的金鑰放進瀏覽器或行動應用程式的程式碼；透過團隊介面確認使用 Ingest only 金鑰傳送的事件。
也可以透過程式檢查資料表與結構：
curl https://api.telemetry.sh/tables \
-H "Authorization: Bearer $TELEMETRY_API_KEY"
接著取得資料表結構：
curl https://api.telemetry.sh/tables/telemetry_quickstart/schema \
-H "Authorization: Bearer $TELEMETRY_API_KEY"
使用同一工作區中具有讀取權限的金鑰查詢剛傳送的事件。如果使用了其他 request_id，請替換下方的 req_demo_001。此查詢檢查最近 24 小時，最多回傳十筆符合條件的紀錄：
curl https://api.telemetry.sh/query \
-H "Authorization: Bearer $TELEMETRY_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <<'JSON'
{"query":"SELECT timestamp_utc, request_id, route_template, status_code, latency_ms, release, environment FROM telemetry_quickstart WHERE request_id = 'req_demo_001' AND timestamp_utc >= now() - INTERVAL '24 hours' ORDER BY timestamp_utc DESC LIMIT 10"}
JSON
檢查回應是否包含 status: "success"，以及 data 中是否有預期紀錄，包括 latency_ms: 184。空的 data 陣列不能證明事件已寫入；請核對金鑰、資料表名稱、識別碼及傳送時間。多筆符合條件的紀錄可能來自重試，不代表多個獨立的應用程式操作。成功讀回範例只驗證這次模擬測試。接著，為一個真實的應用程式操作加入事件紀錄，並查詢對應的業務資料表。
自動化驗證需要具有讀取權限的金鑰。資料表 API 說明分頁、名稱正規化、保留期限及結構回應。
記錄事件資料規格
擴大事件紀錄範圍前，先寫下：
- 事件名稱，以及每筆紀錄代表的業務操作。
- 必填和可選欄位。
- 欄位型別和單位。
- 允許的狀態和錯誤類別。
- 識別與關聯事件的欄位。
- 禁止的欄位。
- 負責人與預期保留期限。
接著閱讀撰寫第一個 SQL 查詢。關於資料表結構的變更策略，請參閱結構演進。