Smart blaze REST API 레퍼런스#
REST API를 사용하면 가상 머신(VM)을 제어할 수 있습니다. 이를 통해 명령줄이나 사용자 정의 스크립트를 사용하여 VM의 수명 주기를 관리하고, 이미지를 업로드하며, 네트워크 설정을 구성할 수 있습니다.
모든 API 엔드포인트는 카메라의 IP 주소를 통해 액세스됩니다:
정보
바꾸기 ${cameraip} 카메라의 실제 IP 주소로.
인증#
Smart Blaze REST API는 무단 접근을 방지하기 위해 챌린지-응답 방식의 세션 기반 인증을 사용합니다. 기본 비밀번호는 카메라마다 고유하며, 카메라에 부착된 라벨에 기재되어 있습니다.
모든 API 엔드포인트(다음을 제외하고) /login)는 세션 쿠키를 통한 인증이 필요합니다. 인증 과정은 다음 세 단계로 이루어집니다:
- 로그인 인증 문제 획득 다음 주소로 GET 요청을 전송하여
/login - 챌린지에서 파생된 논스를 사용하여 챌린지 응답을 계산하기
- 인증 완료를 위해 챌린지 응답을 제출합니다
로그인 인증 문제 받기#
종점: /login
방법: GET
답변: 숨겨진 양식 필드에 논스가 포함된 HTML 페이지
도전 응답 계산#
도전 과제 응답은 다음과 같이 계산해야 합니다:
장소:
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 요청에 세션 쿠키를 포함시켜야 합니다:
인증 예제 (전체)#
다음은 완전한 쉘 스크립트 예제입니다:
#!/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
API 엔드포인트#
정보
아래에 나열된 모든 엔드포인트는 인증이 필요합니다. 먼저 다음을 사용하여 인증을 수행해야 합니다. /login 엔드포인트를 사용하고 요청에 세션 쿠키를 포함시키십시오. 다음을 참조하십시오. 인증 자세한 내용은 해당 섹션을 참조하십시오.
간결함을 위해 아래 예시에서는 인증 단계를 생략하고 API 호출만 보여줍니다. 실제로는 다음을 포함해야 합니다. -b cookies.txt 인증 후 curl 명령어에 다음을 포함하십시오.
VM 제어를 위한 API 호출#
가상 머신 재시작#
가상 머신을 다시 시작하십시오.
종점: /vm/restart
방법: POST
응답: 메인 페이지로 리디렉션됩니다.
예:
가상 머신 시작하기#
가상 머신을 시작하십시오.
종점: /vm/start
방법: POST
응답: 메인 페이지로 리디렉션됩니다.
예:
가상 머신 중지#
가상 머신을 중지하십시오.
종점: /vm/stop
방법: POST
응답: 메인 페이지로 리디렉션됩니다.
예:
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". 비활성화하려면 이 항목을 생략하거나 다른 값을 사용하십시오. |
응답: 메인 페이지로 리디렉션됩니다.
예:
이미지 관리#
사용 가능한 이미지 목록#
설치된 모든 VM 이미지를 활성 상태 및 용량과 함께 나열합니다.
종점: /vm/images
방법: GET
응답: JSON 이미지 객체 배열
응답 필드:
| 분야 | Type | 설명 |
|---|---|---|
name | String | 이미지 이름 |
is_active | 부울 | 이 이미지가 현재 활성화되어 있는지 여부를 나타냅니다. |
size | String | 이미지의 디스크 크기 (사람이 읽을 수 있는 형식, 예: "1.2G") |
예:
답변:
[
{"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 |
성공 응답:
동일한 이름을 가진 비활성 이미지가 존재하고, overwrite 은(는) false:
{
"success": false,
"error": "Image 'debian-arm64-8GB' already exists.",
"needs_confirmation": true
}
그 외의 유효성 검사 실패 시 다음과 같이 반환됩니다:
예:
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
성공 응답:
오류 응답:
정보
언제 set_active=true (기본값), 이 엔드포인트는 업로드 및 활성화 과정에서 VM을 일시적으로 중지합니다. 다음의 경우 set_active=false, 이미지는 실행 중인 VM에 영향을 주지 않은 채로 업로드 및 저장될 뿐입니다.
예시: 새 이미지 업로드 및 활성화 (기본 설정)#
답변:
예시: 활성화하지 않고 업로드하기#
답변:
예시: 업로드 실패 (이미지가 이미 존재함)#
답변:
예시: 기존 이미지 덮어쓰기 및 활성화#
예시: 활성화하지 않고 기존 이미지 덮어쓰기#
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을 일시적으로 중지합니다.
예:
VM 이미지 삭제#
설치된 VM 이미지를 삭제합니다.
종점: /vm/delete_image
방법: POST
Content-Type: application/x-www-form-urlencoded
매개변수:
| Parameter | Type | 필수 | 설명 |
|---|---|---|---|
image_name | String | 예 | 삭제할 이미지의 이름 |
응답: 메인 페이지로 리디렉션됩니다.
정보
현재 선택된 이미지는 삭제할 수 없습니다. 먼저 다른 이미지를 선택하십시오.
예:
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
성공 응답:
오류 응답:
정보
이 엔드포인트는 가상 머신을 일시적으로 중지하고 모든 사용자 데이터를 삭제합니다. 주의해서 사용하십시오!
예:
답변:
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 웹 인터페이스에 접속하십시오:
웹 인터페이스는 다음 작업을 수행할 수 있는 그래픽 사용자 인터페이스를 제공합니다:
- VM 상태 확인
- VM 수명 주기 제어 (시작/중지/재시작)
- 네트워크 설정 구성
- VM 이미지 업로드 및 관리
- 디스크 사용량 모니터링
- 비밀번호 변경
정보
웹 인터페이스는 REST API와 동일한 인증 방식을 사용합니다.
추가 정보#
- 초기 설정 및 구성에 대한 내용은 ‘시작하기’를 참조하십시오.