giip
SES案件登録
4分で読了

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 の点検対象一覧、またはスケジューラーの点検予定一覧を取得します。

クエリ型必須説明
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

1 回の点検実行の結果を記録します(スケジューラーが使用)。サーバーが last_run_at を設定します。

フィールド型必須説明
csnint✅プロジェクト番号
target_idint✅点検した対象
last_resultstring実行結果
watermarkstring次回実行のための進捗マーカー
auth_statusstring更新された到達可能状態
auth_notestring方式メモのみ — 秘密の値は禁止

レスポンス: { "ok": true }

4. 削除 — DELETE

点検対象を 1 つ削除します。

クエリ型必須説明
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 / 403x-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