giipAgentCheckTarget API リファレンス
エージェントが定期的に点検する対象(スラックチャンネル、メールボックス、ウェブ URL、ギットハブリポジトリなど)を管理する API です。認証情報の実値は保存も返却もされず、秘密ではないメタデータ(点検方式と状態)のみを扱います。
📋 概要
giipAgentCheckTarget は GIIP API の REST エンドポイントです。点検対象レジストリに対して 4 つの操作を提供します: 一覧・点検予定の取得(GET)、作成・更新(POST)、実行結果の記録(PUT)、削除(DELETE)。
- エンドポイント:
https://wapi.giipapps.net/api/giipAgentCheckTarget - 認証: ヘッダー
x-api-key: <GIIP SK>— プロジェクト単位の SK です。SK は 1 つの 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
1 回の点検実行の結果を記録します(スケジューラーが使用)。サーバーが last_run_at を設定します。
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
csn | int | ✅ | プロジェクト番号 |
target_id | int | ✅ | 点検した対象 |
last_result | string | 実行結果 | |
watermark | string | 次回実行のための進捗マーカー | |
auth_status | string | 更新された到達可能状態 | |
auth_note | string | 方式メモのみ — 秘密の値は禁止 |
レスポンス: { "ok": true }
4. 削除 — DELETE
点検対象を 1 つ削除します。
| クエリ | 型 | 必須 | 説明 |
|---|---|---|---|
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.ja.md - 元ソースパス:
/help/api-agent-check-target.ja.md - OpenAPI 正本:
giipv3/src/lib/openapiSpec.ts→/giipAgentCheckTarget - 関連 API:
giipfaw/giipAgentCheckTarget