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

Smart blaze REST API 參考#

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

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

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

http://${cameraip}

資訊

取代 ${cameraip} 與您相機的實際 IP 位址。

驗證#

Smart blaze REST API 使用基於工作階段 (session) 的驗證與挑戰-回應機制，以防止未授權的存取。預設密碼對每台相機而言都是唯一的，並印在相機上的標籤上。

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

  1. 取得登入挑戰 透過傳送 GET 請求至 /login
  2. 計算挑戰回應，使用來自挑戰的 nonce
  3. 提交挑戰回應以完成驗證

取得登入驗證挑戰碼#

端點： /login

方法： GET

回應： 包含隱藏表單欄位中 nonce 的 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

參數：

參數 Type 必要 描述
challenge_response 字串 是 計算出的挑戰回應（SHA256 十六進位字串）

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

範例：

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

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

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

完整驗證範例#

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

#!/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）：防止密碼透過網路傳輸。
  • 速率限制（Rate Limiting）：失敗的登入嘗試會受到速率限制，以防範暴力破解攻擊。
  • 工作階段安全性：
    • 僅限 HTTP 的 Cookie（無法透過 JavaScript 存取）
    • SameSite=Strict Cookie 政策
    • 60 秒挑戰逾時
  • 密碼儲存：密碼僅以 SHA256 雜湊值形式儲存。

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

工作階段登出#

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

端點： /logout

方法： POST

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

API 端點#

資訊

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

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

用於 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

參數：

參數 Type 必要 描述
mode 字串 是 網路模式： "DHCP" 或 "Manual"
address 字串 條件式 具有 CIDR 標記法的 IP 位址（例如 "192.168.1.127/24"）。當 mode 是 "Manual".
gateway 字串 否 閘道器 IP 位址 (例如： "192.168.1.1")。若要省略，請留空。
dns0 字串 否 主要 DNS 伺服器位址 (例如： "8.8.8.8")。若要省略，請留空。
dns1 字串 否 次要 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

參數：

參數 Type 必要 描述
wait_console 字串 否 啟用主控台等待模式： "on" 或 "true"。省略或使用任何其他值以停用。

回應：重新導向至主頁面

範例：

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

映像檔管理#

列出可用的映像檔#

列出所有已安裝的 VM 映像及其啟用狀態和大小。

端點： /vm/images

方法： GET

回應：映像物件的 JSON 陣列

回應欄位：

欄位 Type 描述
name 字串 映像名稱
is_active 布林值 表示此映像目前是否為主動狀態。
size 字串 映像的磁碟大小 (人類可讀格式，例如： "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 字串 是 封存檔名稱，包含 .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

參數：

參數 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

參數：

參數 Type 必要 描述
image_name 字串 是 要啟用的映像名稱

回應：重新導向至主頁面

資訊

此端點會暫時停止 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

參數：

參數 Type 必要 描述
image_name 字串 是 要刪除的映像名稱

回應：重新導向至主頁面

資訊

您無法刪除目前處于作用中的映像。請先選擇其他映像。

範例：

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

參數：

參數 Type 必要 描述
old_image_name 字串 是 映像目前的名稱
new_image_name 字串 是 映像的新名稱

回應：重新導向至主頁面

資訊

如果您正在重新命名作用中的映像，此端點會暫時停止 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 Image#

#!/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 網頁介面#

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

xdg-open http://${cameraip}

網頁介面提供可用於下列任務的圖形使用者介面：

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

資訊

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

更多資訊#

  • 如需初始設定與組態的相關資訊，請參閱開始使用。