giipAgentCheckTarget API 參考
用於管理代理定期檢查的目標(Slack 頻道、信箱、網頁 URL、GitHub 儲存庫等)的 API。憑證實際值既不儲存也不回傳,只處理非機密的中繼資料(檢查方式與狀態)。
📋 概述
giipAgentCheckTarget 是 GIIP API 的 REST 端點。它對檢查目標註冊表提供四種操作: 列表·待檢查查詢(GET)、建立·更新(POST)、記錄執行結果(PUT)、刪除(DELETE)。
- 端點:
https://wapi.giipapps.net/api/giipAgentCheckTarget - 驗證: 標頭
x-api-key: <GIIP SK>— 專案範圍的 SK。SK 的範圍限定為一個 CSN,只能讀寫該 CSN 的目標。 - 內容類型 (POST/PUT):
application/json - 隔離: 所有操作都依
csn限定範圍。無法存取其他 CSN 的目標。
⚠️ 不儲存憑證。 本 API 刻意不保留任何機密實際值。POST 送出的目標憑證欄位會被忽略,絕不持久化。只保留非機密的中繼資料:
auth_method(到達目標的方式)、auth_status(是否可達)、auth_note(不含機密值的方式備註)。
🔍 操作
1. 列表 / 待檢查 — GET
查詢某個 CSN 的檢查目標列表,或排程器的待檢查列表。
| 查詢參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
csn | int | 列表模式: 該 CSN 的所有目標 | |
due | bool | 待檢查模式: 現在該檢查的目標(排程器) | |
limit | int | 待檢查模式上限(預設 200) |
回應: { "ok": true, "targets": [ ... ], "count": <n> }
2. 建立或更新 — POST
建立目標(省略 target_id)或更新目標(傳入 target_id)。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
target_id | int | 省略為建立,傳入為更新 | |
csn | int | ✅ | 專案編號; 必須與金鑰範圍一致 |
target_type | string | slack_workspace, slack_channel, email_mailbox, web_url, github_repo, custom 之一 | |
target_ref | string | 僅限非機密識別碼(頻道 ID、URL、儲存庫等) | |
display_name | string | 人類可讀名稱 | |
check_instruction | string | 代理應檢查的內容 | |
interval_min | int | 檢查間隔(分鐘) | |
report_route | string | 回報結果的路徑 | |
auth_method | string | connector, browser_session, human_only, delegated_agent, none_public 之一 | |
auth_status | string | unknown, connected, needs_user_auth, failed 之一 | |
auth_note | string | 僅方式備註 — 禁止機密值 | |
enabled | bool | 目標是否啟用 |
回應: { "ok": true, "target_id": <id> }
憑證欄位會被忽略且不儲存。只傳送上述非機密中繼資料。
3. 記錄檢查結果 — PUT
記錄一次檢查執行的結果(供排程器使用)。伺服器設定 last_run_at。
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
csn | int | ✅ | 專案編號 |
target_id | int | ✅ | 被檢查的目標 |
last_result | string | 執行結果 | |
watermark | string | 下次執行的進度標記 | |
auth_status | string | 更新後的可達狀態 | |
auth_note | string | 僅方式備註 — 禁止機密值 |
回應: { "ok": true }
4. 刪除 — DELETE
刪除一個檢查目標。
| 查詢參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
csn | int | ✅ | 專案編號 |
target_id | int | ✅ | 要刪除的目標 |
回應: { "ok": true }
🛠️ 範例 (cURL)
# 1) 列出 CSN 47 的檢查目標
curl "https://wapi.giipapps.net/api/giipAgentCheckTarget?csn=47" \
-H "x-api-key: <YOUR_SK>"
# 2) 建立檢查目標
curl -X POST "https://wapi.giipapps.net/api/giipAgentCheckTarget" \
-H "x-api-key: <YOUR_SK>" -H "Content-Type: application/json" \
-d '{"csn":47,"target_type":"web_url","target_ref":"https://example.com/status","display_name":"Status page","check_instruction":"Alert if not 200","interval_min":10,"auth_method":"none_public","enabled":true}'
# 3) 記錄檢查執行結果
curl -X PUT "https://wapi.giipapps.net/api/giipAgentCheckTarget" \
-H "x-api-key: <YOUR_SK>" -H "Content-Type: application/json" \
-d '{"csn":47,"target_id":12,"last_result":"ok","watermark":"2026-11-15T02:00:00Z","auth_status":"connected"}'
# 4) 刪除檢查目標
curl -X DELETE "https://wapi.giipapps.net/api/giipAgentCheckTarget?csn=47&target_id=12" \
-H "x-api-key: <YOUR_SK>"
x-api-key是專案範圍的 SK。切勿列印或記錄它。金鑰只能讀寫自己csn內的目標。
疑難排解
| 症狀 | 原因 | 處理 |
|---|---|---|
| 401 / 403 | 缺少或錯誤的 x-api-key,或屬於其他 CSN 的金鑰 | 使用目標 CSN 的 SK |
| POST 後憑證未儲存 | 設計如此 — 憑證實際值不儲存 | 只儲存非機密中繼資料(auth_method/auth_status/auth_note) |
target_id 未更新 | POST 省略 target_id 會建立新目標 | 更新現有目標需傳入 target_id |
| 待檢查列表為空 | 尚未到檢查時間,或 enabled 為假 | 檢查 interval_min 與 enabled |
中繼資料
- 來源檔案:
giipv3/public/help/api-agent-check-target.zh-TW.md - 原始來源路徑:
/help/api-agent-check-target.zh-TW.md - OpenAPI 正本:
giipv3/src/lib/openapiSpec.ts→/giipAgentCheckTarget - 相關 API:
giipfaw/giipAgentCheckTarget