giip
SES 안건 등록
3분 읽기

giipAgentCheckTarget 에이피아이 레퍼런스

에이전트가 주기적으로 점검하는 대상(슬랙 채널, 메일함, 웹 주소, 깃허브 저장소 등)을 관리하는 에이피아이다. 자격증명 실값은 저장하거나 돌려주지 않으며, 비밀이 아닌 메타데이터(점검 방식과 상태)만 다룬다.

📋 개요

giipAgentCheckTarget 은 지프 에이피아이의 레스트 엔드포인트다. 점검 대상 레지스트리에 대해 네 가지 연산을 제공한다: 목록·점검 예정 조회(GET), 생성·수정(POST), 실행 결과 기록(PUT), 삭제(DELETE).

  • 엔드포인트: https://wapi.giipapps.net/api/giipAgentCheckTarget
  • 인증: 헤더 x-api-key: <지프 SK> — 프로젝트 범위 에스케이다. 에스케이는 하나의 씨에스엔으로 범위가 제한되며, 그 씨에스엔의 대상만 읽고 쓸 수 있다.
  • 콘텐츠 타입 (POST/PUT): application/json
  • 격리: 모든 연산은 csn 으로 범위가 제한된다. 다른 씨에스엔의 대상에는 접근할 수 없다.

⚠️ 자격증명은 저장하지 않는다. 이 에이피아이는 의도적으로 비밀 실값을 보관하지 않는다. POST 로 보낸 대상 자격증명 필드는 무시되며 절대 저장되지 않는다. 비밀이 아닌 메타데이터만 보관한다: auth_method(대상에 접근하는 방식), auth_status(접근 가능 여부), auth_note(비밀 값이 없는 방식 메모).

🔍 연산

1. 목록 / 점검 예정 — GET

한 씨에스엔의 점검 대상 목록, 또는 스케줄러의 점검 예정 목록을 조회한다.

쿼리타입필수설명
csnint목록 모드: 이 씨에스엔의 모든 대상
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비밀이 아닌 식별자만 (채널 아이디, 주소, 저장소 등)
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) 씨에스엔 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 는 프로젝트 범위 에스케이다. 절대 출력하거나 로그에 남기지 않는다. 키는 자기 csn 안의 대상만 읽고 쓸 수 있다.

문제 해결

증상원인조치
401 / 403x-api-key 없음·잘못됨, 또는 다른 씨에스엔의 키대상 씨에스엔의 에스케이를 사용
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.ko.md
  • 원본 경로: /help/api-agent-check-target.ko.md
  • 오픈에이피아이 정본: giipv3/src/lib/openapiSpec.ts → /giipAgentCheckTarget
  • 관련 에이피아이: giipfaw/giipAgentCheckTarget