edge

엣지 플릿 관리, 디바이스 토큰 및 디바이스 인증 기반 자가 등록/하트비트.

이 태그에는 인증 방식이 다른 두 부류가 섞여 있습니다.

• 플릿 관리 API: 사용자 세션(JWT/쿠키) + X-Tenant + RBAC 권한이 필요합니다. (/fleet, /devices/*, 토큰 발급/회전/폐기, 재시작)
• 인제스트 API: 사용자 로그인 없이 X-Edge-Token 디바이스 토큰만으로 호출합니다. (/register, /heartbeat, /containers/pull, /models*)

How-To: 엣지 디바이스 온보딩 & 인제스트 호출#

1. 디바이스 등록 (관리자, 1회): 관리자(ADMIN)가 POST /api/v1/edge/devices 로 디바이스를 만들면 응답으로 평문 토큰이 단 한 번 반환됩니다({"id", "token"}). 서버에는 HMAC-SHA256 해시만 저장되므로 이 토큰을 디바이스에 안전하게 보관하세요. 분실 시 POST /api/v1/edge/devices/{id}/token:rotate 로 재발급합니다.
2. 디바이스에 토큰 설치: 이후 모든 인제스트 요청은 X-Edge-Token: <token> 헤더로 보냅니다. 사용자 로그인/X-Tenant 헤더는 필요 없으며, 테넌트는 토큰에 바인딩되어 자동 적용됩니다.
3. 자가 등록 핸드셰이크: 부팅 시 POST /api/v1/edge/register 를 호출해 os/sdk_version/location 메타데이터를 갱신하고 디바이스를 ACTIVE로 표시합니다.
4. 텔레메트리 전송: 주기적으로 POST /api/v1/edge/heartbeat 로 cpu/gpu/mem/disk 지표를 보냅니다. (토큰에 telemetry:write 스코프 필요)
5. 모델 컨테이너 풀: GET /api/v1/edge/containers/pull?model=&version= 로 배포할 이미지 참조를 받습니다. (토큰에 container:pull 스코프 필요)
6. 모델 조회 & 다운로드: GET /api/v1/edge/models 로 테넌트에 등록된 모델 목록을, GET /api/v1/edge/models/{name}/versions 로 버전 이력을 조회하고, GET /api/v1/edge/models/{name}/{version}/download 로 아티팩트를 내려받습니다. (토큰에 models:read 스코프 필요)

토큰 스코프: 발급 시 기본값은 telemetry:write, inference:write, container:pull, models:read 입니다. 엔드포인트가 요구하는 스코프가 토큰에 없으면 403이 반환됩니다. 만료(기본 365일)·폐기된 토큰은 401입니다.

Swagger UI에서는 상단 Authorize 버튼의 EdgeToken 항목에 토큰을 입력하면 인제스트 엔드포인트를 바로 시험해 볼 수 있습니다.

GET /api/v1/edge/fleet#

GET/api/v1/edge/fleet

플릿 상태

호출자의 테넌트에 속한 모든 엣지 디바이스를 파생 상태 및 최신 텔레메트리 스냅샷(cpu/gpu/mem, 마지막 하트비트)과 함께 나열합니다.

Permission: VIEW

Parameters

Responses

GET /api/v1/edge/devices/{device_id}#

GET/api/v1/edge/devices/{device_id}

디바이스 상세

단일 디바이스의 전체 상세 정보를 반환합니다: 파생 상태, OS/SDK 메타데이터, 최신 리소스 스냅샷, 배포된 컨테이너 목록.

Permission: VIEW

Parameters

Responses

PATCH /api/v1/edge/devices/{device_id}#

PATCH/api/v1/edge/devices/{device_id}

디바이스 정보 수정

디바이스의 설치 위치를 바꿉니다.

Permission: SETTINGS

Parameters

Request body: application/json, DeviceUpdate

Responses

DELETE /api/v1/edge/devices/{device_id}#

DELETE/api/v1/edge/devices/{device_id}

디바이스 삭제

디바이스와 그에 딸린 모든 기록을 영구 삭제합니다.

Permission: SETTINGS

Parameters

Responses

GET /api/v1/edge/devices/{device_id}/logs#

GET/api/v1/edge/devices/{device_id}/logs

디바이스 로그

디바이스의 하트비트 페이로드를 최신순 로그 피드로 반환합니다.

Permission: OPERATE

Parameters

Responses

POST /api/v1/edge/devices#

POST/api/v1/edge/devices

디바이스 + 토큰 등록

호출자의 테넌트 아래에 새 엣지 디바이스를 프로비저닝하고 첫 번째 액세스 토큰을 발급합니다.

Permission: SETTINGS

Request body: application/json, DeviceCreate

Responses

POST /api/v1/edge/devices/{device_id}/token:rotate#

POST/api/v1/edge/devices/{device_id}/token:rotate

디바이스 토큰 회전

엣지 디바이스에 새 액세스 토큰을 발급하고 기존 토큰을 무효화합니다.

Permission: SETTINGS

Parameters

Responses

POST /api/v1/edge/devices/{device_id}/token:revoke#

POST/api/v1/edge/devices/{device_id}/token:revoke

디바이스 토큰 폐기

디바이스의 모든 활성 토큰을 폐기하여 인제스트 접근을 차단합니다.

Permission: SETTINGS

Parameters

Responses

PATCH /api/v1/edge/devices/{device_id}/token:scopes#

PATCH/api/v1/edge/devices/{device_id}/token:scopes

디바이스 토큰 스코프 수정

디바이스의 활성 토큰에 부여된 스코프를 토큰 재발급 없이 교체합니다.

Permission: SETTINGS

Parameters

Request body: application/json, ScopesUpdate

Responses

POST /api/v1/edge/devices/{device_id}/restart#

POST/api/v1/edge/devices/{device_id}/restart

디바이스 재시작

대상 디바이스에 대한 재시작 명령을 큐에 등록합니다.

Permission: OPERATE

Parameters

Responses

POST /api/v1/edge/devices/{device_id}/offline#

POST/api/v1/edge/devices/{device_id}/offline

디바이스 오프라인 차단

대상 디바이스를 서버에서 끊거나(blocked=true) 되돌립니다.

Permission: OPERATE

Parameters

Request body: application/json, OfflineUpdate

Responses

POST /api/v1/edge/register#

POST/api/v1/edge/register

디바이스 자가 등록

디바이스 SDK 자가 등록 핸드셰이크입니다.

Request body: application/json, RegisterBody

Responses

POST /api/v1/edge/heartbeat#

POST/api/v1/edge/heartbeat

텔레메트리 하트비트

디바이스로부터 텔레메트리 하트비트를 인제스트합니다.

Request body: application/json, HeartbeatBody

Responses

GET /api/v1/edge/containers/pull#

GET/api/v1/edge/containers/pull

컨테이너 이미지 해석

디바이스가 풀할 수 있도록 모델 버전에 대한 완전한 형식의 컨테이너 이미지 참조를 해석합니다.

Parameters

Responses

GET /api/v1/edge/models#

GET/api/v1/edge/models

등록 모델 목록 (디바이스 토큰)

디바이스가 자신의 테넌트에 등록된 모델 목록을 조회합니다.

Responses

GET /api/v1/edge/models/{name}/versions#

GET/api/v1/edge/models/{name}/versions

모델 버전 이력 (디바이스 토큰)

디바이스가 등록 모델의 버전 이력을 조회합니다.

Parameters

Responses

GET /api/v1/edge/models/{name}/{version}/download#

GET/api/v1/edge/models/{name}/{version}/download

모델 버전 아티팩트 다운로드 (디바이스 토큰)

디바이스가 모델 버전의 아티팩트를 파일로 내려받습니다.

Parameters

Responses

POST /api/v1/edge/telemetry#

POST/api/v1/edge/telemetry

텔레메트리 배치 인제스트

오프라인 동안 쌓인 구조화 레코드를 한 번에 받습니다.

Request body: application/json, TelemetryBatch

Responses

POST /api/v1/edge/inference#

POST/api/v1/edge/inference

추론 결과 배치 인제스트

엣지에서 수행한 추론 결과를 배치로 받습니다.

Request body: application/json, InferenceBatch

Responses

POST /api/v1/edge/uploads#

POST/api/v1/edge/uploads

파일 업로드 세션 시작

재개 가능한 파일 전송을 엽니다.

Request body: application/json, UploadInit

Responses

GET /api/v1/edge/uploads/{upload_id}#

GET/api/v1/edge/uploads/{upload_id}

업로드 재개 지점 조회

재시작한 디바이스가 "어디까지 받았나" 를 묻는 자리입니다.

Parameters

Responses

PUT /api/v1/edge/uploads/{upload_id}/chunks/{index}#

PUT/api/v1/edge/uploads/{upload_id}/chunks/{index}

업로드 청크 전송

청크 하나를 보냅니다 (application/octet-stream).

Parameters

Responses

POST /api/v1/edge/uploads/{upload_id}:complete#

POST/api/v1/edge/uploads/{upload_id}:complete

업로드 마감

모든 청크가 도착했음을 알리고 즉시 돌아옵니다 (202).

Parameters

Responses

GET /api/v1/edge/commands#

GET/api/v1/edge/commands

명령 롱폴 수신

대기 중인 명령을 가져옵니다. 없으면 최대 wait 초 붙잡습니다.

Parameters

Responses

POST /api/v1/edge/commands/{command_id}:ack#

POST/api/v1/edge/commands/{command_id}:ack

명령 처리 결과 보고

명령 처리 결과를 보고합니다.

Parameters

Request body: application/json, CommandAck

Responses

GET /api/v1/edge/config#

GET/api/v1/edge/config

디바이스 정책 조회

이 디바이스에 적용되는 정책(보존·동기화·주기)을 돌려줍니다.

Responses

GET /api/v1/edge/devices/{device_id}/telemetry#

GET/api/v1/edge/devices/{device_id}/telemetry

디바이스 텔레메트리 조회

디바이스가 올린 구조화 레코드를 최신순으로 조회합니다 (VIEW).

Parameters

Responses

GET /api/v1/edge/devices/{device_id}/inference#

GET/api/v1/edge/devices/{device_id}/inference

디바이스 추론 결과 조회

디바이스가 올린 추론 결과를 최신순으로 조회합니다 (VIEW).

Parameters

Responses

GET /api/v1/edge/devices/{device_id}/uploads#

GET/api/v1/edge/devices/{device_id}/uploads

디바이스 업로드 목록

디바이스가 올린(또는 올리는 중인) 파일 전송을 나열합니다 (VIEW).

Parameters

Responses

GET /api/v1/edge/devices/{device_id}/commands#

GET/api/v1/edge/devices/{device_id}/commands

디바이스 명령 이력

이 디바이스에 내린 명령과 그 결과를 나열합니다 (VIEW).

Parameters

Responses

POST /api/v1/edge/devices/{device_id}/commands#

POST/api/v1/edge/devices/{device_id}/commands

디바이스 명령 큐잉

디바이스가 다음 폴링 때 가져갈 명령을 큐에 넣습니다 (OPERATE).

Parameters

Request body: application/json, CommandCreate

Responses

GET /api/v1/edge/devices/{device_id}/policy#

GET/api/v1/edge/devices/{device_id}/policy

디바이스 정책 조회

적용 중인 정책과 리비전을 돌려줍니다 (VIEW).

Parameters

Responses

PUT /api/v1/edge/devices/{device_id}/policy#

PUT/api/v1/edge/devices/{device_id}/policy

디바이스 정책 변경

정책을 바꾸고 리비전을 올립니다 (SETTINGS).

Parameters

Request body: application/json, PolicyUpdate

Responses