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
한 씨에스엔의 점검 대상 목록, 또는 스케줄러의 점검 예정 목록을 조회한다.
| 쿼리 | 타입 | 필수 | 설명 |
|---|---|---|---|
csn | int | 목록 모드: 이 씨에스엔의 모든 대상 | |
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 | 비밀이 아닌 식별자만 (채널 아이디, 주소, 저장소 등) | |
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) 씨에스엔 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 / 403 | x-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