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-CN.md
  • 原始源路径: /help/api-agent-check-target.zh-CN.md
  • OpenAPI 正本: giipv3/src/lib/openapiSpec.ts → /giipAgentCheckTarget
  • 相关 API: giipfaw/giipAgentCheckTarget