Function Compute：BrowserTool瀏覽器

Puppeteer 串連樣本

const puppeteer = require('puppeteer-core');

// 從BrowserTool服務詳情頁擷取此端點
const BROWSERTOOL_CDP_ENDPOINT = 'wss://{accountID}.agentrun-data.ap-southeast-1.aliyuncs.com/sandboxes/{sandboxID}/ws/automation?tenantId={accountID}';

async function main() {
  const browser = await puppeteer.connect({
    browserWSEndpoint: BROWSERTOOL_CDP_ENDPOINT,
  });

  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({ path: 'example.png' });
  console.log('Screenshot taken!');
  await browser.close();
}

main();

Playwright 串連樣本

const { chromium } = require('playwright-core');

// 從BrowserTool 服務詳情頁擷取此端點
const BROWSERTOOL_CDP_ENDPOINT = 'wss://{accountID}.agentrun-data.ap-southeast-1.aliyuncs.com/sandboxes/{sandboxId}/ws/automation?tenantId={accountID}';

async function main() {
  const browser = await chromium.connectOverCDP({
    endpointURL: BROWSERTOOL_CDP_ENDPOINT,
  });

  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({ path: 'example.png' });
  console.log('Screenshot taken!');
  await browser.close();
}

main();

推薦方案：使用線上 noVNC 用戶端

1. 訪問 noVNC 官方提供的線上用戶端：https://novnc.com/noVNC/vnc.html

2. 在串連設定中，中填入以下串連資訊

   • 主機：{accountID}.agentrun-data.ap-southeast-1.aliyuncs.com

   • 連接埠：443

   • 路徑：sandboxes/{sandboxID}/ws/livestream?tenantId={accountID}

3. 點擊串連，即可看到瀏覽器介面。

如果想要自訂前端整合，允許完全控制 VNC 視圖的展現形式和互動邏輯。需要引入 noVNC 的核心 JS 庫，並在前端代碼中進行初始化。樣本地址：https://github.com/novnc/noVNC/blob/master/vnc_lite.html

備選方案：使用Docker鏡像

如果您需要在本地或離線環境中使用，可以運行我們預置的 noVNC Docker 鏡像。

1. 在本地終端運行 Docker 命令啟動 noVNC 用戶端容器：

   docker run -p 8184:80 -d --rm registry.cn-shanghai.aliyuncs.com/fc-demo2/custom-container-repository:browsertool-sandbox-vnc-client_v0.3.1

2. 開啟瀏覽器訪問 http://localhost:8184。

3. 在串連設定中，中填入以下串連資訊：

   • 主機：{accountID}.agentrun-data.ap-southeast-1.aliyuncs.com

   • 連接埠：80

   • 路徑：sandboxes/{sandboxID}/ws/livestream?tenantId={accountID}

   點擊串連，即可看到瀏覽器介面。

基本資料

• 端點: GET /recordings/

• 功能: 返回 VNC 錄製檔案清單

• 標籤: 錄製管理

請求參數

功能特性

• 支援分頁查詢

• 自動識別錄製狀態（正在錄製/已完成）

• 按建立時間降序排列（最新的在前）

• 返迴文件詳細資料（檔案名稱、大小、建立時間等）

響應格式

成功響應（200 OK）

{
  "recordings": [
    {
      "filename": "vnc_global_20251116_103022_seg000.mkv",
      "sessionId": "vnc_global_20251116_103022",
      "segment": 0,
      "size": 15728640,
      "createdAt": "2025-11-16T10:30:22+08:00",
      "format": "mkv",
      "downloadUrl": "/recordings/vnc_global_20251116_103022_seg000.mkv",
      "recordingType": "vnc",
      "status": "completed"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

響應欄位說明

錯誤響應

• 400 Bad Request: 無效請求（參數錯誤）

• 500 Internal Server Error: 內部伺服器錯誤

請求樣本

# 擷取第一頁，每頁 20 條記錄（預設）
curl -X GET "http://localhost:3000/recordings/"

# 擷取第二頁，每頁 10 條記錄
curl -X GET "http://localhost:3000/recordings/?page=2&page_size=10"

# 擷取所有錄製檔案（設定較大的 page_size）
curl -X GET "http://localhost:3000/recordings/?page_size=100"

基本資料

• 端點: GET /recordings/{filename}

• 功能: 下載指定的錄製檔案

• 標籤: 錄製管理

請求參數

功能特性

• MKV 格式支援流式寫入

• 檔案可以在錄製過程中下載和播放

• 只允許下載 .mkv 檔案

• 自動化佈建正確的 Content-Type (video/x-matroska)

響應格式

成功響應 (200 OK)

• Content-Type: video/x-matroska

• Body: 二進位視頻資料

錯誤響應

• 400 Bad Request: 無效請求

  {
    "error": "Invalid filename"
  }

  • 檔案名稱無效

  • 不是MKV檔案

• 404 Not Found: 檔案未找到

• 500 Internal Server Error: 內部伺服器錯誤

請求樣本

# 下載錄製檔案
curl -X GET "http://localhost:3000/recordings/vnc_global_20251116_103022_seg000.mkv" \
  -o vnc_global_20251116_103022_seg000.mkv

# 在瀏覽器中直接存取
http://localhost:3000/recordings/vnc_global_20251116_103022_seg000.mkv

注意事項

1. 檔案格式限制: 只允許下載 .mkv 檔案

2. 流式支援: MKV 格式支援流式寫入，可以在錄製過程中下載

3. 播放器相容: MKV 檔案可以使用 VLC、Chrome、Firefox 等主流播放器播放

基本資料

• 端點: DELETE /recordings/{filename}

• 功能: 刪除指定的錄製檔案

• 標籤: 錄製管理

請求參數

功能特性

• 支援刪除 .mkv 檔案

• MKV 支援流式寫入，檔案可以在錄製過程中刪除

• 在 VNC 目錄中尋找檔案

• 刪除正在錄製的檔案時需謹慎，確保錄製已停止

響應格式

成功響應 (200 OK)

{
  "message": "Recording file deleted successfully",
  "filename": "vnc_global_20251116_103022_seg000.mkv"
}

響應欄位說明

錯誤響應

• 400 Bad Request: 無效請求

  • 檔案名稱無效

  • 不是支援的檔案類型

• 404 Not Found: 檔案未找到

• 500 Internal Server Error: 內部伺服器錯誤

請求樣本

# 刪除指定的錄製檔案
curl -X DELETE "http://localhost:3000/recordings/vnc_global_20251116_103022_seg000.mkv"

# 使用 jq 格式化輸出
curl -X DELETE "http://localhost:3000/recordings/vnc_global_20251116_103022_seg000.mkv" | jq

注意事項

1. 不可恢複: 刪除操作不可恢複，請謹慎操作

2. 錄製中的檔案: 刪除正在錄製的檔案時需確保錄製已停止

3. 檔案格式限制: 只支援刪除 .mkv 檔案

通用錯誤響應格式

{
  "code": 1001,
  "error": "invalid request"
}

常見錯誤碼