giip
SES 商機登記
3分鐘閱讀

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 的檢查目標列表,或排程器的待檢查列表。

查詢參數型別必填說明
csnint列表模式: 該 CSN 的所有目標
duebool待檢查模式: 現在該檢查的目標(排程器)
limitint待檢查模式上限(預設 200)

回應: { "ok": true, "targets": [ ... ], "count": <n> }

2. 建立或更新 — POST

建立目標(省略 target_id)或更新目標(傳入 target_id)。

欄位型別必填說明
target_idint省略為建立,傳入為更新
csnint✅專案編號; 必須與金鑰範圍一致
target_typestringslack_workspace, slack_channel, email_mailbox, web_url, github_repo, custom 之一
target_refstring僅限非機密識別碼(頻道 ID、URL、儲存庫等)
display_namestring人類可讀名稱
check_instructionstring代理應檢查的內容
interval_minint檢查間隔(分鐘)
report_routestring回報結果的路徑
auth_methodstringconnector, browser_session, human_only, delegated_agent, none_public 之一
auth_statusstringunknown, connected, needs_user_auth, failed 之一
auth_notestring僅方式備註 — 禁止機密值
enabledbool目標是否啟用

回應: { "ok": true, "target_id": <id> }

憑證欄位會被忽略且不儲存。只傳送上述非機密中繼資料。

3. 記錄檢查結果 — PUT

記錄一次檢查執行的結果(供排程器使用)。伺服器設定 last_run_at。

欄位型別必填說明
csnint✅專案編號
target_idint✅被檢查的目標
last_resultstring執行結果
watermarkstring下次執行的進度標記
auth_statusstring更新後的可達狀態
auth_notestring僅方式備註 — 禁止機密值

回應: { "ok": true }

4. 刪除 — DELETE

刪除一個檢查目標。

查詢參數型別必填說明
csnint✅專案編號
target_idint✅要刪除的目標

回應: { "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