沙箱实例

沙箱实例 API 用于创建、查询和管理沙箱生命周期，并获取沙箱日志和资源监控指标。

创建沙箱

描述

从指定模板创建一个沙箱实例。

请求路径

POST /sandboxes

请求参数

injections 支持引用已保存规则，也支持直接传入内联规则：

base_url 的 host 精确匹配；包含 path 时按规范化 path 精确匹配，path 末尾的 * 表示前缀匹配。if_headers 和 if_queries 只用于缩小请求匹配范围，不是授权边界。

resources 当前支持 github_repository 和 kodo。

GitHub 仓库资源字段：

Kodo 存储桶资源字段：

Kodo 资源只支持使用七牛 AK/SK 鉴权创建沙箱；仅使用沙箱 API Key 的创建请求不支持挂载 Kodo 资源。AK/SK 用于平台侧访问 Bucket，不会以明文暴露给沙箱。

响应字段

请求示例

curl -X POST "$QINIU_SANDBOX_API_URL/sandboxes" \
  -H "X-API-Key: $QINIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateID": "base",
    "timeout": 300,
    "metadata": {
      "project": "demo"
    },
    "envVars": {
      "APP_ENV": "dev"
    }
  }'

创建沙箱并挂载 Kodo 存储桶资源：

curl -X POST "$QINIU_SANDBOX_API_URL/sandboxes" \
  -H "X-API-Key: $QINIU_API_KEY" \
  -H "Authorization: Qiniu <SignedToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "templateID": "base",
    "resources": [
      {
        "type": "kodo",
        "bucket": "my-bucket",
        "mount_path": "/mnt/kodo",
        "prefix": "datasets/demo",
        "read_only": true
      }
    ]
  }'

其中 SignedToken 需要用七牛 AK/SK 生成。只带 X-API-Key、不带 AK/SK 签名的请求不支持创建 Kodo 资源沙箱。

创建沙箱并使用内联注入：

curl -X POST "$QINIU_SANDBOX_API_URL/sandboxes" \
  -H "X-API-Key: $QINIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateID": "base",
    "injections": [
      {
        "type": "openai",
        "api_key": "sk-xxx"
      },
      {
        "type": "http",
        "base_url": "https://api.example.com/v1/*",
        "if_headers": {
          "X-Scope": "prod"
        },
        "headers": {
          "Authorization": "Bearer secret-token"
        }
      }
    ]
  }'

响应示例

{
  "templateID": "base",
  "sandboxID": "sbx_123456",
  "envdVersion": "0.1.0",
  "envdAccessToken": "envd-token",
  "trafficAccessToken": "traffic-token",
  "domain": "sbx_123456.example.qiniuapi.com"
}

查询沙箱列表

描述

查询当前账号下的沙箱列表。推荐使用 GET /v2/sandboxes，支持状态过滤和分页。

请求路径

GET /v2/sandboxes

兼容路径：

GET /sandboxes

请求参数

响应字段

返回沙箱对象数组：

请求示例

curl -G "$QINIU_SANDBOX_API_URL/v2/sandboxes" \
  -H "X-API-Key: $QINIU_API_KEY" \
  --data-urlencode "state=running" \
  --data-urlencode "limit=20"

获取沙箱详情

请求路径

GET /sandboxes/{sandboxID}

路径参数

响应字段

删除沙箱

描述

终止并删除指定沙箱。

请求路径

DELETE /sandboxes/{sandboxID}

路径参数

响应字段

成功时返回 204 No Content，无响应体。

暂停沙箱

请求路径

POST /sandboxes/{sandboxID}/pause

成功时返回 204 No Content。

恢复沙箱

请求路径

POST /sandboxes/{sandboxID}/resume

请求参数

成功时返回沙箱连接信息，字段同创建沙箱响应。

连接沙箱

描述

获取沙箱连接信息。如果沙箱处于暂停状态，会先恢复沙箱；如果沙箱正在运行，只延长 TTL。

请求路径

POST /sandboxes/{sandboxID}/connect

请求参数

成功时返回沙箱连接信息，字段同创建沙箱响应。

设置沙箱超时时间

请求路径

POST /sandboxes/{sandboxID}/timeout

请求参数

成功时返回 204 No Content。

延长沙箱存活时间

请求路径

POST /sandboxes/{sandboxID}/refreshes

请求参数

成功时返回 204 No Content。

查询沙箱日志

请求路径

GET /sandboxes/{sandboxID}/logs

请求参数

响应字段

查询沙箱指标

请求路径

GET /sandboxes/{sandboxID}/metrics

请求参数

响应字段

返回指标对象数组：

批量查询沙箱指标

请求路径

GET /sandboxes/metrics

请求参数

请求示例

curl -G "$QINIU_SANDBOX_API_URL/sandboxes/metrics" \
  -H "X-API-Key: $QINIU_API_KEY" \
  --data-urlencode "sandbox_ids=sbx_123456,sbx_789012"

响应字段

返回以沙箱 ID 为 key 的指标对象：

相关文档

• API 概述
• 沙箱生命周期
• 沙箱监控指标
• 沙箱元数据
• 沙箱网络访问
• 资源挂载