명령 보내기

POST

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

const url = 'https://dev.api.endueos.com/api/v1/devices/res_01J9ZK3Q8M4XW7D2N5R6T0V1BC/commands';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"command":"run_program","input":{"program":"python3","args":["-c","print(6*7)"]},"request_id":"job-42","wait_ms":25000}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://dev.api.endueos.com/api/v1/devices/res_01J9ZK3Q8M4XW7D2N5R6T0V1BC/commands \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "command": "run_program", "input": { "program": "python3", "args": [ "-c", "print(6*7)" ] }, "request_id": "job-42", "wait_ms": 25000 }'

Device 의 에이전트에게 도구 하나를 실행시킨다. POST /resources/{resource_id}/commands 와 같다. 계정 잔액이 0 이하면 402 INSUFFICIENT_CREDITS — 끝난 명령 1건마다 단가표의 command 만큼 쓴다.

가이드 — 기기

인증

파라미터

경로 파라미터

device_id

필수

Device 의 id — Resource 와 같은 res_ 다 (v0.1.0 이 이미 냈다).

string

/^res_[0-9A-HJKMNP-TV-Z]{26}$/

예시

res_01J9ZK3Q8M4XW7D2N5R6T0V1BC

요청 본문^필수

application/json

object

command

필수

도구 이름.

string

/^[a-z_]{1,64}$/

input

도구 입력. 에이전트가 자기 스키마로 검증한다.

object

timeout_ms

에이전트가 실행하는 시간의 예산. 보낸 순간부터 센다 (줄에서 기다린 시간은 넣지 않는다). 없으면 OS 의 default_command_timeout_ms.

integer format: int32

>= 1000 <= 120000

request_id

멱등 키. 없으면 서버가 만든다. sys: 로 시작할 수 없다. 끝난 뒤 24시간 안에 같은 키로 다시 보내면 같은 명령을 돌려준다.

string

/^[A-Za-z0-9._:-]{1,200}$/

store_image

출력의 이미지(image_base64 또는 image_blob)를 저장 객체로 옮기고 storage_object_id 로 바꿔 돌려준다.

boolean

wait_ms

이 시간 안에 끝나면 201 + 출력, 아니면 202 를 받는다. 0 이면 바로 202. 0~25000, 기본 25000.

integer format: int32

<= 25000

queue_ttl_ms

에이전트가 오프라인이거나 전달 창이 찼을 때 줄에서 기다릴 최대 시간. 0 이면 기다리지 않고 409 RESOURCE_OFFLINE·429 RESOURCE_BUSY. 0~3600000, 기본 0.

integer format: int32

<= 3600000

retain_output

동기로 건넨 출력도 보관한다 (24시간). 동기로 건네지 못한 출력은 이 값과 무관하게 보관한다.

boolean

예시

{
  "command": "run_program",
  "input": {
    "program": "python3",
    "args": [
      "-c",
      "print(6*7)"
    ]
  },
  "request_id": "job-42",
  "wait_ms": 25000
}

응답

201

만들었다.

application/json

object

data

필수

명령이 끝났을 때의 응답 — 기록에 출력이 붙는다.

object

command_id

필수

string

/^cmd_[0-9A-HJKMNP-TV-Z]{26}$/

request_id

필수

string

resource_id

필수

string

/^res_[0-9A-HJKMNP-TV-Z]{26}$/

agent_id

필수

string

/^agnt_[0-9A-HJKMNP-TV-Z]{26}$/

station_id

필수

string

/^stn_[0-9A-HJKMNP-TV-Z]{26}$/

actor_type

필수

string

허용 값: user api_key

actor_id

필수

string

command

필수

string

status

필수

string

허용 값: queued dispatched running cancelling succeeded failed timed_out cancelled expired unknown

error

필수

Any of:

string
null

string

error_code

필수

Any of:

string
null

string

timeout_ms

필수

integer format: int32

queue_ttl_ms

필수

integer format: int32

duration_ms

필수

Any of:

integer
null

integer format: int64

created_at

필수

string format: date-time

dispatched_at

필수

Any of:

string
null

string format: date-time

completed_at

필수

Any of:

string
null

string format: date-time

output_url

필수

Any of:

string
null

string

output_expires_at

필수

Any of:

string
null

string format: date-time

late_status

필수

Any of:

string
null

늦게 도착한 답의 상태 — unknown 으로 끝난 뒤에 온 것.

string

허용 값: succeeded failed timed_out

late_at

필수

Any of:

string
null

string format: date-time

updated_at

필수

string format: date-time

output

필수

Any of:

object
null

object

meta

필수

object

request_id

필수

string

timestamp

필수

string format: date-time

duration

서버 처리 시간(ms).

integer format: int32

예시

{
  "data": {
    "command_id": "cmd_01J9ZK3Q8M4XW7D2N5R6T0V1BC",
    "resource_id": "res_01J9ZK3Q8M4XW7D2N5R6T0V1BC",
    "agent_id": "agnt_01J9ZK3Q8M4XW7D2N5R6T0V1BC",
    "station_id": "stn_01J9ZK3Q8M4XW7D2N5R6T0V1BC",
    "actor_type": "user",
    "status": "queued",
    "late_status": "succeeded"
  }
}

202

받았지만 아직 끝나지 않았다. Location 으로 상태를 묻는다. Retry-After 는 다음 조회까지 기다릴 초.

application/json

object

data

필수

명령 기록. 입력 원문은 남기지 않는다. 출력은 보관한 경우에만 output_url 로 24시간 받을 수 있다.

object

command_id

필수

string

/^cmd_[0-9A-HJKMNP-TV-Z]{26}$/

request_id

필수

string

resource_id

필수

string

/^res_[0-9A-HJKMNP-TV-Z]{26}$/

agent_id

필수

string

/^agnt_[0-9A-HJKMNP-TV-Z]{26}$/

station_id

필수

string

/^stn_[0-9A-HJKMNP-TV-Z]{26}$/

actor_type

필수

string

허용 값: user api_key

actor_id

필수

string

command

필수

string

status

필수

string

허용 값: queued dispatched running cancelling succeeded failed timed_out cancelled expired unknown

error

필수

Any of:

string
null

string

error_code

필수

Any of:

string
null

string

timeout_ms

필수

integer format: int32

queue_ttl_ms

필수

integer format: int32

duration_ms

필수

Any of:

integer
null

integer format: int64

created_at

필수

string format: date-time

dispatched_at

필수

Any of:

string
null

string format: date-time

completed_at

필수

Any of:

string
null

string format: date-time

output_url

필수

Any of:

string
null

string

output_expires_at

필수

Any of:

string
null

string format: date-time

late_status

필수

Any of:

string
null

늦게 도착한 답의 상태 — unknown 으로 끝난 뒤에 온 것.

string

허용 값: succeeded failed timed_out

late_at

필수

Any of:

string
null

string format: date-time

updated_at

필수

string format: date-time

meta

필수

object

request_id

필수

string

timestamp

필수

string format: date-time

duration

서버 처리 시간(ms).

integer format: int32

예시

{
  "data": {
    "command_id": "cmd_01J9ZK3Q8M4XW7D2N5R6T0V1BC",
    "resource_id": "res_01J9ZK3Q8M4XW7D2N5R6T0V1BC",
    "agent_id": "agnt_01J9ZK3Q8M4XW7D2N5R6T0V1BC",
    "station_id": "stn_01J9ZK3Q8M4XW7D2N5R6T0V1BC",
    "actor_type": "user",
    "status": "queued",
    "late_status": "succeeded"
  }
}

응답 헤더

Location

필수

string

Retry-After

필수

integer format: int32

400

요청 형식이 틀렸다 — VALIDATION_ERROR(details.errors[]) 또는 BAD_REQUEST. 본문은 오류 봉투.

401

인증이 없거나 무효다 — UNAUTHORIZED. 본문은 오류 봉투.

402

크레딧이 없다 — INSUFFICIENT_CREDITS (충전하면 다시 된다). 본문은 오류 봉투.

404

없거나 내 것이 아니다 — *_NOT_FOUND. 본문은 오류 봉투.

409

지금 상태와 충돌한다 — 코드는 위 설명을 본다. 본문은 오류 봉투.

429

한도를 넘었다 — Retry-After 초 뒤에 다시. 본문은 오류 봉투.

500

서버 오류 — INTERNAL_ERROR. 본문은 오류 봉투.

503

의존 서비스에 닿지 못했다 — 잠시 뒤 다시. 본문은 오류 봉투.

504

결과를 알 수 없다 — COMMAND_OUTCOME_UNKNOWN, 같은 request_id 로 다시. 본문은 오류 봉투.

명령 보내기

인증

파라미터

경로 파라미터

예시

요청 본문필수

예시

응답

201

예시

202

예시

응답 헤더

400

401

402

404

409

429

500

503

504

요청 본문^필수