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