명령
엔드포인트: /api/events/commands/
원격 서버에서 명령을 실행하고 관리합니다.
List
명령 목록 조회
명령 목록을 페이지별로 조회합니다.
요청
GET /api/events/commands/쿼리 매개변수
| 매개변수 | 자료형 | 설명 |
|---|---|---|
server | UUID | 서버 ID가 정확히 일치하는 명령만 조회함 |
id__in | string | 명령 ID로 조회함(쉼표로 구분한 UUID, 최대 100개) |
shell | string | 셸 유형이 정확히 일치하는 명령만 조회함 |
requested_by | integer | 요청한 사용자 ID가 정확히 일치하는 명령만 조회함 |
requested_by_isnull | boolean | 요청자가 없는 명령만 조회함 |
is_scheduled | boolean | 향후 실행 예약은 true, 과거 또는 즉시 실행은 false |
verification_status | string | AI 검증 상태로 조회함. 예: rejected, advisory |
risk_level | string | 위험 수준으로 조회함: INFO, LOW, MEDIUM, HIGH, CRITICAL. 대소문자를 구분하지 않으며 여러 값은 쉼표로 구분함(HIGH,CRITICAL). 알 수 없는 값에는 invalid_input과 함께 400을 반환함 |
added_at__gte | datetime | 이 시각 이후 또는 같은 시각에 생성된 명령(ISO 8601) |
added_at__lt | datetime | 이 시각 전에 생성된 명령(ISO 8601). added_at__gte와 함께 쓰면 끝 시각이 제외되는 구간이므로 연속된 구간에서 같은 명령이 중복 집계되지 않음 |
search | string | 서버 이름, 명령줄 또는 요청자 이름으로 검색함 |
ordering | string | 정렬 필드(기본값: -scheduled_at). 선택 가능한 값: added_at, scheduled_at, delivered_at, acked_at, handled_at |
page | integer | 페이지 번호 |
page_size | integer | 페이지당 결과 수(기본값: 15, 최대: 100) |
응답
{
"count": 85,
"next": "https://your-workspace.ap1.alpacon.io/api/events/commands/?page=2",
"previous": null,
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"shell": "system",
"line": "df -h",
"success": true,
"result": "Filesystem Size Used Avail Use% Mounted on\n/dev/xvda1 20G 8.5G 11G 46% /",
"status": {
"text": "Success",
"color": "success",
"cancellable": false,
"message": "Finished at 2024-01-15 10:30:45"
},
"response_delay": 0.125,
"elapsed_time": 0.023,
"added_at": "2024-01-15T10:30:44Z",
"server": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8",
"username": "ubuntu",
"groupname": "alpacon",
"requested_by": {
"id": 1,
"username": "admin",
"email": "admin@example.com"
},
"scheduled_at": "2024-01-15T10:30:44Z"
}
]
}예시
curl "https://your-workspace.ap1.alpacon.io/api/events/commands/?ordering=-scheduled_at&page_size=20" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""여러 명령의 상태 조회
대시보드나 자동화에서 결과를 주기적으로 조회하는 등 여러 명령을 한꺼번에 추적할 때는 명령마다
GET /api/events/commands/{command_id}/를 호출하지 말고, 쉼표로 구분한 명령 ID 목록을
id__in에 전달하세요. page_size=100도 설정하세요. 기본 페이지 크기는 15이므로 15개가 넘는
ID를 요청할 때 이를 설정하지 않으면 모든 결과 대신 첫 페이지와 next 링크만 반환됩니다.
curl "https://your-workspace.ap1.alpacon.io/api/events/commands/?id__in=550e8400-e29b-41d4-a716-446655440000,9b52a7c4-13de-48f6-a01b-7f3e5d982c44&page_size=100" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""한 번에 최대 100개의 ID를 요청할 수 있습니다. 이 한도를 넘으면
event_command_bulk_limit_exceeded와 함께 400을 반환하며, 유효한 UUID가 아닌 값이 하나라도
있으면 400을 반환합니다. id__in 값이 비어 있으면 이 매개변수를 무시하므로, 매개변수를 생략한
것처럼 접근할 수 있는 전체 목록을 반환합니다. 결과는 요청한 ID 순서가 아니라 ordering
매개변수의 순서(기본값: -scheduled_at)를 따르므로 각 결과의 id 필드로 요청 목록과
대조하세요. 접근할 수 없거나 더 이상 존재하지 않는 명령의 ID는 별도 알림 없이 결과에서
제외됩니다. 제외된 ID가 있는지 확인하려면 응답의 count와 요청한 고유 ID의 개수를 비교하세요.
명령 상태 흐름
각 명령은 아래 타임스탬프에 따라 진행됩니다.
| 필드 | 설명 |
|---|---|
added_at | 명령 생성 |
scheduled_at | 예약 실행 시각 |
delivered_at | 서버로 전송 |
acked_at | 서버가 명령 수신을 확인하고 실행을 시작함 |
handled_at | 실행 완료 |
status 객체는 text, color, cancellable, message 필드로 사람이 읽을 수 있는 상태 요약을
제공합니다.
오류 응답
| 상태 | 오류 코드 | 설명 |
|---|---|---|
| 400 | api_insufficient_data | 필수 데이터 누락(대상 서버 또는 명령줄 누락) |
| 400 | command_inline_credential | line에 인라인 자격 증명이 포함됨(시크릿처럼 보이는 KEY=VALUE, 비밀번호 플래그 또는 비밀번호가 포함된 연결 문자열). env로 옮기거나, 그대로 진행하려면 credential_exposure_acknowledged: true 설정 필요 |
| 400 | event_command_bulk_limit_exceeded | id__in에 명령 ID 100개 초과 전달 |
| 403 | api_token_acl_not_allowed | 토큰 ACL에서 허용하지 않는 명령. 재시도로 해결되지 않으므로 토큰 규칙을 확대해야 함. 명령 패턴과 sudo 참고 |
| 404 | — | 명령을 찾을 수 없음. 오류 코드가 없는 {"detail": "..."} 응답 |
| 409 | event_command_already_sent | 명령 취소 불가(서버에 이미 전달됨) |
| 503 | server_not_connected | 서버 오프라인 |