跳至內容
測試伺服器
開發伺服器

Smart blaze REST API 參考#

本主題說明 Smart blaze 相機提供的 REST API。

REST API 可用於控制虛擬機 (VM)。它允許您從命令列或使用自訂腳本來管理 VM 生命週期、上傳映像以及設定網路。

所有 API 端點皆透過相機的 IP 位址進行存取：

http://${cameraip}

資訊

將 ${cameraip} 使用您相機的實際 IP 位址。

驗證#

Smart blaze REST API 使用基於工作階段的驗證，並採用挑戰應答 (challenge-response) 機制來防止未授權存取。預設密碼每台相機都不同，並印在相機的標籤上。

所有 API 端點（除了 /login之外）都需要透過工作階段 Cookie 進行驗證。驗證包含三個步驟：

  1. 取得登入挑戰 透過向以下位置傳送 GET 請求： /login
  2. 計算挑戰應答，使用來自挑戰的隨機數 (nonce)
  3. 提交挑戰應答以完成驗證

取得登入驗證挑戰碼#

端點： /login

方法： GET

回應： 包含隱藏表單欄位中隨機數的 HTML 頁面

計算挑戰回應#

必須按如下方式計算挑戰應答：

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

其中：

  • nonce 是來自登入挑戰的值。
  • password 是您的純文字密碼。
  • SHA256 會產生小寫的十六進位字串。

範例（使用 shell）：

# 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

Parameters：

Property Type 必填 描述
challenge_response String 是 計算出的挑戰應答（SHA256 十六進位字串）

回應： 成功時重新導向至主頁面。失敗時傳回帶有錯誤的登入頁面。

範例：

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

驗證成功後，請在所有後續的 API 請求中包含工作階段 Cookie：

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

完整驗證範例#

以下是一個完整的 shell 腳本範例：

#!/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"

安全功能#

  • 挑戰應答驗證 (Challenge-Response Authentication)：防止在網路上傳輸密碼。
  • 速率限制：對失敗的登入嘗試進行速率限制，以防止暴力破解攻擊。
  • 工作階段安全性：
    • 僅限 HTTP 的 Cookie (無法透過 JavaScript 存取)
    • SameSite=Strict Cookie 政策
    • 60 秒挑戰逾時
  • 密碼儲存：密碼僅以 SHA256 雜湊值儲存。

使用者可以透過網頁介面設定自訂密碼。

工作階段登出#

若要登出並清除工作階段：

端點： /logout

方法： POST

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

API 端點#

資訊

下方列出的所有端點都需要驗證。您必須先使用 /login 端點進行驗證，並在您的請求中包含工作階段 Cookie。請參閱 驗證 章節以了解詳細資訊。

為求簡潔，下方的範例顯示未包含驗證步驟的 API 呼叫。實際上，請在驗證後於您的 curl -b cookies.txt 指令中包含。

用於 VM 控制的 API 呼叫#

重新啟動 VM#

重新啟動虛擬機器。

端點： /vm/restart

方法： POST

回應：重新導向至主頁

範例：

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

啟動 VM#

啟動虛擬機器。

端點： /vm/start

方法： POST

回應：重新導向至主頁

範例：

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

停止 VM#

停止虛擬機器。

端點： /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

Parameters：

Property Type 必填 描述
mode String 是 網路模式： "DHCP" 或 "Manual"
address String 條件式 帶有 CIDR 標記法的 IP 位址 (例如： "192.168.1.127/24")。當 mode 為 "Manual".
gateway String 否 時為必填 "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

Parameters：

Property 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 Boolean 表示此映像目前是否為啟用狀態。
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 Integer 是 以位元組為單位的壓縮檔大小
overwrite Boolean 否 允許替換現有的未啟用映像。預設值： 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

Parameters：

Property 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

Parameters：

Property 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

Parameters：

Property 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

Parameters：

Property 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 與 kernel，並重設 VM 組態。

端點： /vm/factory_reset

方法： POST

回應：JSON

成功回應：

{
  "success": true
}

錯誤回應：

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

資訊

此端點會暫時停止 VM 並刪除所有使用者資料。請謹慎使用！

範例：

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

回應：

{"success":true}

錯誤處理#

傳回 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

在未啟用 VM 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

在已安裝的 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 Image#

#!/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 執行時，指令碼會上傳新影像，且 VM 在啟動後將使用新影像重新啟動。這支援 VM 自我更新。

VM Control Web Interface#

如需互動式管理，請存取 Smart blaze VM Control 網頁介面：

xdg-open http://${cameraip}

網頁介面提供圖形化使用者介面，可用於執行下列工作：

  • 檢視 VM 狀態
  • 控制 VM 生命週期（啟動/停止/重新啟動）
  • 設定網路設定
  • 上傳與管理 VM 影像
  • 監控磁碟使用量
  • 變更密碼

資訊

網頁介面使用與 REST API 相同的驗證機制。

更多資訊#

  • 如需關於初始設定與組態的資訊，請參閱 Getting Started。