콘텐츠로 바로 가기
STAGING SERVER
DEVELOPMENT SERVER

Smart blaze REST API 레퍼런스#

이 항목에서는 Smart Blaze 카메라에서 제공하는 REST API에 대해 설명합니다.

REST API를 사용하면 가상 머신(VM)을 제어할 수 있습니다. 이를 통해 명령줄이나 사용자 정의 스크립트를 사용하여 VM의 수명 주기를 관리하고, 이미지를 업로드하며, 네트워크 설정을 구성할 수 있습니다.

모든 API 엔드포인트는 카메라의 IP 주소를 통해 액세스됩니다:

http://${cameraip}

정보

바꾸기 ${cameraip} 카메라의 실제 IP 주소로.

인증#

Smart Blaze REST API는 무단 접근을 방지하기 위해 챌린지-응답 방식의 세션 기반 인증을 사용합니다. 기본 비밀번호는 카메라마다 고유하며, 카메라에 부착된 라벨에 기재되어 있습니다.

모든 API 엔드포인트(다음을 제외하고) /login)는 세션 쿠키를 통한 인증이 필요합니다. 인증 과정은 다음 세 단계로 이루어집니다:

  1. 로그인 인증 문제 획득 다음 주소로 GET 요청을 전송하여 /login
  2. 챌린지에서 파생된 논스를 사용하여 챌린지 응답을 계산하기
  3. 인증 완료를 위해 챌린지 응답을 제출합니다

로그인 인증 문제 받기#

종점: /login

방법: GET

답변: 숨겨진 양식 필드에 논스가 포함된 HTML 페이지

도전 응답 계산#

도전 과제 응답은 다음과 같이 계산해야 합니다:

response = SHA256(nonce + ":" + SHA256(password))

장소:

  • nonce 로그인 인증 과정에서 얻은 값입니다.
  • password 는 귀하의 일반 텍스트 비밀번호입니다.
  • SHA256은 소문자 16진수 문자열을 생성합니다.

예시 (셸 사용):

# Get the nonce from the login page
NONCE=$(curl -s http://${cameraip}/login | grep -oP 'id="challenge-nonce"[^>]*value="\K[^"]+')

# Your password
PASSWORD="blaze-oh-yeah"

# Compute password hash
PASSWORD_HASH=$(echo -n "$PASSWORD" | sha256sum | awk '{print $1}')

# Compute challenge response
RESPONSE=$(echo -n "${NONCE}:${PASSWORD_HASH}" | sha256sum | awk '{print $1}')

챌린지 답변 제출하기#

종점: /login

방법: POST

Content-Type: application/x-www-form-urlencoded

매개변수:

Parameter Type 필수 설명
challenge_response String 예 계산된 챌린지-응답(SHA256 16진수 문자열)

응답: 성공 시 메인 페이지로 리디렉션됩니다. 실패 시 오류 메시지가 포함된 로그인 페이지를 반환합니다.

예:

curl -c cookies.txt -b cookies.txt -X POST http://${cameraip}/login \
  -d "challenge_response=${RESPONSE}"

인증에 성공한 후에는 이후의 모든 API 요청에 세션 쿠키를 포함시켜야 합니다:

# Using curl with cookie file
curl -b cookies.txt -X POST http://${cameraip}/vm/restart

인증 예제 (전체)#

다음은 완전한 쉘 스크립트 예제입니다:

#!/bin/bash

CAMERA_IP="192.168.1.123"
PASSWORD="blaze-oh-yeah"

# Get login challenge
echo "Getting login challenge..."
NONCE=$(curl -s -c cookies.txt http://${CAMERA_IP}/login | \
    grep -oP 'id="challenge-nonce"[^>]*value="\K[^"]+')

if [ -z "$NONCE" ]; then
    echo "Failed to get login challenge"
    exit 1
fi

# Compute challenge response
PASSWORD_HASH=$(echo -n "$PASSWORD" | sha256sum | awk '{print $1}')
RESPONSE=$(echo -n "${NONCE}:${PASSWORD_HASH}" | sha256sum | awk '{print $1}')

# Login
echo "Logging in..."
curl -s -b cookies.txt -c cookies.txt -X POST http://${CAMERA_IP}/login \
    -d "challenge_response=${RESPONSE}" > /dev/null

# Now you can make authenticated API calls
echo "Making authenticated API call..."
curl -b cookies.txt -X POST http://${CAMERA_IP}/vm/restart

echo "Done"

보안 기능#

  • 챌린지-응답 방식 인증: 네트워크를 통한 비밀번호 전송을 방지합니다.
  • 접속 제한: 무차별 대입 공격을 방지하기 위해 로그인 실패 횟수에 제한이 적용됩니다.
  • 세션 보안:
    • HTTP 전용 쿠키 ( JavaScript 를 통해서는 접근할 수 없음)
    • SameSite=Strict 쿠키 정책
    • 60초 챌린지 시간 초과
  • 비밀번호 저장: 비밀번호는 SHA256 해시 값으로만 저장됩니다.

사용자는 웹 인터페이스를 통해 사용자 지정 비밀번호를 설정할 수 있습니다.

세션 로그아웃#

로그아웃하고 세션을 지우려면:

종점: /logout

방법: POST

curl -b cookies.txt -X POST http://${cameraip}/logout

API 엔드포인트#

정보

아래에 나열된 모든 엔드포인트는 인증이 필요합니다. 먼저 다음을 사용하여 인증을 수행해야 합니다. /login 엔드포인트를 사용하고 요청에 세션 쿠키를 포함시키십시오. 다음을 참조하십시오. 인증 자세한 내용은 해당 섹션을 참조하십시오.

간결함을 위해 아래 예시에서는 인증 단계를 생략하고 API 호출만 보여줍니다. 실제로는 다음을 포함해야 합니다. -b cookies.txt 인증 후 curl 명령어에 다음을 포함하십시오.

VM 제어를 위한 API 호출#

가상 머신 재시작#

가상 머신을 다시 시작하십시오.

종점: /vm/restart

방법: POST

응답: 메인 페이지로 리디렉션됩니다.

예:

curl -X POST http://${cameraip}/vm/restart

가상 머신 시작하기#

가상 머신을 시작하십시오.

종점: /vm/start

방법: POST

응답: 메인 페이지로 리디렉션됩니다.

예:

curl -X POST http://${cameraip}/vm/start

가상 머신 중지#

가상 머신을 중지하십시오.

종점: /vm/stop

방법: POST

응답: 메인 페이지로 리디렉션됩니다.

예:

curl -X POST http://${cameraip}/vm/stop

VM 구성을 위한 API 호출#

IP 설정 구성#

VM의 네트워크 설정(DHCP 또는 고정 IP)을 구성합니다.

종점: /vm/ip

방법: POST

Content-Type: application/x-www-form-urlencoded

매개변수:

Parameter Type 필수 설명
mode String 예 네트워크 모드: "DHCP" 또는 "Manual"
address String 조건부 CIDR 표기법을 사용한 IP 주소 (예: "192.168.1.127/24"). 다음의 경우 필수입니다. mode 은(는) "Manual".
gateway String 아니요 게이트웨이 IP 주소 (예: "192.168.1.1"). 생략하려면 비워 두십시오.
dns0 String 아니요 주 DNS 서버 주소 (예: "8.8.8.8"). 생략하려면 비워 두십시오.
dns1 String 아니요 보조 DNS 서버 주소. 생략하려면 비워 두십시오.

응답: 메인 페이지로 리디렉션됩니다.

정보

이 엔드포인트는 네트워크 구성 변경 사항을 적용하기 위해 VM을 일시적으로 중지합니다.

예시: 고정 IP 설정#
curl -X POST http://${cameraip}/vm/ip \
  -d "mode=Manual" \
  -d "address=192.168.1.127/24" \
  -d "gateway=192.168.1.1" \
  -d "dns0=8.8.8.8" \
  -d "dns1=8.8.4.4"
예: 활성화 DHCP#
curl -X POST http://${cameraip}/vm/ip \
  -d "mode=DHCP" \
  -d "address=192.168.1.127/24" \
  -d "gateway=" \
  -d "dns0=" \
  -d "dns1="

VM 설정 업데이트#

VM 동작 설정을 구성합니다.

종점: /vm/settings

방법: POST

Content-Type: application/x-www-form-urlencoded

매개변수:

Parameter Type 필수 설명
wait_console String 아니요 콘솔 대기 모드 활성화: "on" 또는 "true". 비활성화하려면 이 항목을 생략하거나 다른 값을 사용하십시오.

응답: 메인 페이지로 리디렉션됩니다.

예:

curl -X POST http://${cameraip}/vm/settings \
  -d "wait_console=on"

이미지 관리#

사용 가능한 이미지 목록#

설치된 모든 VM 이미지를 활성 상태 및 용량과 함께 나열합니다.

종점: /vm/images

방법: GET

응답: JSON 이미지 객체 배열

응답 필드:

분야 Type 설명
name String 이미지 이름
is_active 부울 이 이미지가 현재 활성화되어 있는지 여부를 나타냅니다.
size String 이미지의 디스크 크기 (사람이 읽을 수 있는 형식, 예: "1.2G")

예:

curl http://${cameraip}/vm/images

답변:

[
  {"name": "debian-arm64-min", "is_active": true, "size": "1.2G"},
  {"name": "custom-app", "is_active": false, "size": "2.4G"}
]

VM 이미지 업로드 확인#

아카이브를 전송하기 전에 VM 이미지를 업로드할 수 있는지 확인하십시오. 이 과정에서는 업로드 엔드포인트와 동일한 검증 기준을 적용하여 파일 이름, .tar.gz 확장자, 이미지 이름, 덮어쓰기 제한 사항 및 사용 가능한 저장 공간을 확인합니다.

종점: /vm/check_image_uploadable

방법: POST

Content-Type: application/json

요청 필드:

분야 Type 필수 설명
filename String 예 .tar.gz 확장자를 포함한 아카이브 이름
size 정수 예 아카이브 크기 (바이트)
overwrite 부울 아니요 기존의 비활성 이미지를 교체할 수 있습니다. 기본값: false

성공 응답:

{
  "success": true,
  "image_name": "debian-arm64-8GB"
}

동일한 이름을 가진 비활성 이미지가 존재하고, overwrite 은(는) false:

{
  "success": false,
  "error": "Image 'debian-arm64-8GB' already exists.",
  "needs_confirmation": true
}

그 외의 유효성 검사 실패 시 다음과 같이 반환됩니다:

{
  "success": false,
  "error": "Error message"
}

예:

curl -X POST http://${cameraip}/vm/check_image_uploadable \
  -H "Content-Type: application/json" \
  -d '{"filename":"debian-arm64-8GB.tar.gz","size":2147483648,"overwrite":false}'

정보

검사가 성공적으로 완료되었다고 해서 이미지 이름이나 저장 공간이 예약되는 것은 아닙니다. 업로드 엔드포인트에서는 이러한 검사를 다시 수행합니다. 아카이브 내용과 파일 유형은 아카이브가 업로드된 후에만 유효성 검증이 가능합니다.

VM 이미지 업로드#

새로운 VM 이미지 아카이브를 업로드하십시오. 아카이브에는 루트 파일 시스템(rootfs) 및 커널 파일이 포함되어 있어야 합니다.

종점: /vm/image

방법: POST

Content-Type: multipart/form-data

매개변수:

Parameter Type 필수 설명
file 파일 예 VM 이미지 아카이브(.tar.gz 형식)
overwrite 쿼리 아니요 설정: "true" 동일한 이름의 기존 이미지를 덮어쓰기 위해. 기본값: "false"
set_active 쿼리 아니요 설정: "true" 업로드된 이미지를 즉시 활성화하려면 (VM이 재시작됩니다). 다음으로 설정하십시오. "false" 활성화하지 않고 업로드하려면. 기본값: "true"

지원되는 아카이브 콘텐츠:

업로드된 압축 파일에는 다음 내용이 포함되어 있어야 합니다:

  • rootfs 파일: rootfs.qcow2, rootfs.img, 또는 rootfs.raw
  • 커널 파일: kernel

자세한 내용은 ‘VM 이미지 구조’를 참조하십시오.

답변: JSON

성공 응답:

{
  "success": true
}

오류 응답:

{
  "success": false,
  "error": "Error message"
}
{
  "success": false,
  "error": "Image 'image-name' already exists.",
  "needs_confirmation": true
}
{
  "success": false,
  "error": "Cannot overwrite the active image: image-name"
}

정보

언제 set_active=true (기본값), 이 엔드포인트는 업로드 및 활성화 과정에서 VM을 일시적으로 중지합니다. 다음의 경우 set_active=false, 이미지는 실행 중인 VM에 영향을 주지 않은 채로 업로드 및 저장될 뿐입니다.

예시: 새 이미지 업로드 및 활성화 (기본 설정)#
curl -F "file=@debian-arm64-8GB.tar.gz" http://${cameraip}/vm/image

답변:

{"success":true}
예시: 활성화하지 않고 업로드하기#
curl -F "file=@debian-arm64-8GB.tar.gz" "http://${cameraip}/vm/image?set_active=false"

답변:

{"success":true}
예시: 업로드 실패 (이미지가 이미 존재함)#
curl -F "file=@debian-arm64-8GB.tar.gz" http://${cameraip}/vm/image

답변:

{"error":"Image 'debian-arm64-8GB' already exists.","needs_confirmation":true,"success":false}
예시: 기존 이미지 덮어쓰기 및 활성화#
curl -F "file=@debian-arm64-8GB.tar.gz" "http://${cameraip}/vm/image?overwrite=true"
예시: 활성화하지 않고 기존 이미지 덮어쓰기#
curl -F "file=@debian-arm64-8GB.tar.gz" "http://${cameraip}/vm/image?overwrite=true&set_active=false"

활성 이미지 선택#

활성 VM 이미지를 다른 설치된 이미지로 변경합니다.

종점: /vm/select_image

방법: POST

Content-Type: application/x-www-form-urlencoded

매개변수:

Parameter Type 필수 설명
image_name String 예 활성화할 이미지의 이름

응답: 메인 페이지로 리디렉션됩니다.

정보

이 엔드포인트는 활성 이미지를 전환하기 위해 VM을 일시적으로 중지합니다.

예:

curl -X POST http://${cameraip}/vm/select_image \
  -d "image_name=debian-arm64-8GB"

VM 이미지 삭제#

설치된 VM 이미지를 삭제합니다.

종점: /vm/delete_image

방법: POST

Content-Type: application/x-www-form-urlencoded

매개변수:

Parameter Type 필수 설명
image_name String 예 삭제할 이미지의 이름

응답: 메인 페이지로 리디렉션됩니다.

정보

현재 선택된 이미지는 삭제할 수 없습니다. 먼저 다른 이미지를 선택하십시오.

예:

curl -X POST http://${cameraip}/vm/delete_image \
  -d "image_name=old-image"

VM 이미지 이름 변경#

설치된 VM 이미지의 이름을 변경합니다.

종점: /vm/rename_image

방법: POST

Content-Type: application/x-www-form-urlencoded

매개변수:

Parameter Type 필수 설명
old_image_name String 예 이미지의 현재 이름
new_image_name String 예 이미지의 새 이름

응답: 메인 페이지로 리디렉션됩니다.

정보

활성 이미지의 이름을 변경하는 경우, 이 엔드포인트는 VM을 일시적으로 중지합니다.

예:

curl -X POST http://${cameraip}/vm/rename_image \
  -d "old_image_name=debian-arm64-8GB" \
  -d "new_image_name=my-custom-vm"

시스템 유지보수#

초기화#

VM을 공장 출하 시 기본값으로 초기화합니다. 이렇게 하면 모든 사용자 지정 VM 이미지가 제거되고, 원래의 rootfs와 커널이 복원되며, VM 구성이 초기화됩니다.

종점: /vm/factory_reset

방법: POST

답변: JSON

성공 응답:

{
  "success": true
}

오류 응답:

{
  "success": false,
  "error": "Error message"
}

정보

이 엔드포인트는 가상 머신을 일시적으로 중지하고 모든 사용자 데이터를 삭제합니다. 주의해서 사용하십시오!

예:

curl -X POST http://${cameraip}/vm/factory_reset

답변:

{"success":true}

Error Handling#

JSON 를 반환하는 API 엔드포인트에는 다음이 포함됩니다. success 필드:

  • true: 작업이 성공적으로 완료되었습니다.
  • false: 작업이 실패했습니다. 다음을 확인하십시오. error 자세한 내용을 보려면 해당 필드를 참조하십시오.

일부 오류 응답에는 추가 필드가 포함될 수 있습니다:

  • needs_confirmation: 다음으로 설정 true 해당 작업에 명시적인 확인이 필요한 경우(예: 기존 이미지 덮어쓰기).

일반적인 사용 사례#

사용자 지정 VM 이미지 업로드 및 활성화#

#!/bin/bash

CAMERA_IP="192.168.1.123"
PASSWORD="blaze-oh-yeah"  # Replace with your camera's password
IMAGE_FILE="my-custom-vm.tar.gz"

# Authenticate
NONCE=$(curl -s -c cookies.txt http://${CAMERA_IP}/login | \
    grep -oP 'id="challenge-nonce"[^>]*value="\K[^"]+')
PASSWORD_HASH=$(echo -n "$PASSWORD" | sha256sum | awk '{print $1}')
RESPONSE=$(echo -n "${NONCE}:${PASSWORD_HASH}" | sha256sum | awk '{print $1}')
curl -s -b cookies.txt -c cookies.txt -X POST http://${CAMERA_IP}/login \
    -d "challenge_response=${RESPONSE}" > /dev/null

# Upload and activate the image archive (default behavior)
RESULT=$(curl -b cookies.txt -F "file=@${IMAGE_FILE}" http://${CAMERA_IP}/vm/image)
echo "$RESULT"

# The VM will automatically restart with the new image

가상 머신 이미지를 활성화하지 않고 업로드하기#

#!/bin/bash

CAMERA_IP="192.168.1.123"
PASSWORD="blaze-oh-yeah"  # Replace with your camera's password
IMAGE_FILE="backup-vm.tar.gz"

# Authenticate (authentication code omitted for brevity, see above)

# Upload the image without activating it (VM keeps running)
RESULT=$(curl -b cookies.txt -F "file=@${IMAGE_FILE}" \
    "http://${CAMERA_IP}/vm/image?set_active=false")
echo "$RESULT"

# The image is now stored but not active. You can activate it later using /vm/select_image

설치된 이미지 간 전환#

# Authenticate (see above for full authentication example)
# Then select a different image
curl -b cookies.txt -X POST http://${cameraip}/vm/select_image \
    -d "image_name=debian-arm64-base"

직접 연결을 위한 고정 IP 설정#

# Authenticate first, then configure network
curl -b cookies.txt -X POST http://${cameraip}/vm/ip \
  -d "mode=Manual" \
  -d "address=192.168.1.200/24" \
  -d "gateway=192.168.1.1" \
  -d "dns0=8.8.8.8" \
  -d "dns1="

VM 이미지 배포 자동화#

#!/bin/bash

CAMERA_IP="192.168.1.123"
PASSWORD="blaze-oh-yeah"  # Replace with your camera's password
IMAGE_FILE="production-vm.tar.gz"

# Function to authenticate
authenticate() {
    echo "Authenticating..."
    NONCE=$(curl -s -c cookies.txt http://${CAMERA_IP}/login | \
        grep -oP 'id="challenge-nonce"[^>]*value="\K[^"]+')

    if [ -z "$NONCE" ]; then
        echo "Failed to get login challenge"
        return 1
    fi

    PASSWORD_HASH=$(echo -n "$PASSWORD" | sha256sum | awk '{print $1}')
    RESPONSE=$(echo -n "${NONCE}:${PASSWORD_HASH}" | sha256sum | awk '{print $1}')

    curl -s -b cookies.txt -c cookies.txt -X POST http://${CAMERA_IP}/login \
        -d "challenge_response=${RESPONSE}" > /dev/null

    return 0
}

# Authenticate
if ! authenticate; then
    echo "Authentication failed"
    exit 1
fi

# Upload VM image without activating it
echo "Uploading VM image to camera..."
RESPONSE=$(curl -s -b cookies.txt -F "file=@${IMAGE_FILE}" \
    "http://${CAMERA_IP}/vm/image?set_active=false")

if echo "$RESPONSE" | grep -q '"success":true'; then
    echo "Upload successful!"
else
    echo "Upload failed:"
    echo "$RESPONSE"
    exit 1
fi

# Activate the uploaded image
echo "Activating new VM image..."
IMAGE_NAME="${IMAGE_FILE%.tar.gz}"
curl -s -b cookies.txt -X POST http://${CAMERA_IP}/vm/select_image \
    -d "image_name=${IMAGE_NAME}"

echo "VM is restarting with new image."

정보

이 스크립트는 카메라에 네트워크로 접속할 수 있는 모든 시스템에서 실행할 수 있으며, 여기에는 가상 머신(VM) 내부도 포함됩니다. 가상 머신 내에서 이 스크립트를 실행하면 새로운 이미지가 업로드되며, 활성화 후 가상 머신은 새로운 이미지로 재시작됩니다. 이를 통해 가상 머신을 자동으로 업데이트할 수 있습니다.

VM 제어 웹 인터페이스#

대화형 관리를 하려면 Smart Blaze VM Control 웹 인터페이스에 접속하십시오:

xdg-open http://${cameraip}

웹 인터페이스는 다음 작업을 수행할 수 있는 그래픽 사용자 인터페이스를 제공합니다:

  • VM 상태 확인
  • VM 수명 주기 제어 (시작/중지/재시작)
  • 네트워크 설정 구성
  • VM 이미지 업로드 및 관리
  • 디스크 사용량 모니터링
  • 비밀번호 변경

정보

웹 인터페이스는 REST API와 동일한 인증 방식을 사용합니다.

추가 정보#