模板

模板 API 用于创建和管理沙箱模板。模板构建通常分为创建模板构建记录、上传构建文件、启动构建、查询构建状态几个步骤。

创建模板

描述

创建一个新模板，并返回待启动的构建任务信息。

请求路径

POST /v3/templates

兼容路径：

POST /v2/templates
POST /templates

请求参数

POST /v3/templates 参数：

参数名称	参数类型	必填	描述
name	string	否	模板名称
cpuCount	integer	否	模板默认 CPU 核数，最小为 1
memoryMB	integer	否	模板默认内存大小，单位为 MiB，最小为 128

POST /templates 兼容接口参数：

参数名称	参数类型	必填	描述
dockerfile	string	是	用于构建模板的 Dockerfile 内容
alias	string	否	模板别名
startCmd	string	否	模板启动后执行的启动命令
readyCmd	string	否	模板启动后执行的就绪检查命令
cpuCount	integer	否	模板默认 CPU 核数
memoryMB	integer	否	模板默认内存大小，单位为 MiB

响应字段

成功时返回 202 Accepted，表示构建任务已创建。

请求示例

curl -X POST "$QINIU_SANDBOX_API_URL/v3/templates" \
  -H "X-API-Key: $QINIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-template",
    "cpuCount": 2,
    "memoryMB": 1024
  }'

获取构建文件上传链接

描述

获取模板构建文件的上传链接。hash 是构建层文件的内容哈希；如果服务端缓存中已经存在该文件，响应中的 present 为 true。

请求路径

GET /templates/{templateID}/files/{hash}

路径参数

参数名称	参数类型	必填	描述
templateID	string	是	模板 ID
hash	string	是	构建文件内容哈希

响应字段

字段名称	字段类型	描述
present	boolean	文件是否已经存在于缓存中
url	string	文件上传地址；当 present 为 false 时使用

启动模板构建

描述

启动指定模板的构建任务。

请求路径

POST /v2/templates/{templateID}/builds/{buildID}

兼容路径：

POST /templates/{templateID}/builds/{buildID}

路径参数

参数名称	参数类型	必填	描述
templateID	string	是	模板 ID
buildID	string	是	构建 ID

请求参数

参数名称	参数类型	必填	描述
fromImage	string	否	使用的基础镜像
fromTemplate	string	否	使用的基础模板
fromImageRegistry	object	否	私有镜像仓库配置
force	boolean	否	是否强制跳过缓存重新构建；默认为 false
steps	array	否	构建步骤列表
startCmd	string	否	模板启动后执行的启动命令
readyCmd	string	否	模板启动后执行的就绪检查命令

成功时返回 202 Accepted。

查询默认模板列表

请求路径

GET /default-templates

响应字段

返回模板对象数组：

字段名称	字段类型	描述
templateID	string	模板 ID
buildID	string	最近一次成功构建 ID
cpuCount	integer	CPU 核数
memoryMB	integer	内存大小，单位为 MiB
diskSizeMB	integer	磁盘大小，单位为 MiB
public	boolean	模板是否公开
aliases	string[]	模板别名
createdAt	string	模板创建时间
updatedAt	string	模板更新时间
lastSpawnedAt	string	最近一次使用时间
spawnCount	integer	模板被使用次数
buildCount	integer	模板构建次数
envdVersion	string	envd 版本
buildStatus	string	最近构建状态

查询模板列表

请求路径

GET /templates

请求参数

参数名称	参数类型	必填	描述
teamID	string	否	已废弃的团队 ID 参数

响应字段同默认模板列表。

获取模板详情

请求路径

GET /templates/{templateID}

请求参数

参数名称	参数类型	必填	描述
nextToken	string	否	构建列表分页游标
limit	integer	否	每页构建数量，范围 1 到 100，默认 100

响应字段

字段名称	字段类型	描述
templateID	string	模板 ID
public	boolean	模板是否公开
aliases	string[]	模板别名
createdAt	string	模板创建时间
updatedAt	string	模板更新时间
lastSpawnedAt	string	最近一次使用时间
spawnCount	integer	模板被使用次数
builds	array	构建列表

更新模板

请求路径

PATCH /templates/{templateID}

请求参数

参数名称	参数类型	必填	描述
public	boolean	否	是否将模板设为公开

成功时返回更新后的模板信息。

重新构建模板

请求路径

POST /templates/{templateID}

请求参数

参数同 POST /templates 兼容接口。成功时返回 202 Accepted。

删除模板

请求路径

DELETE /templates/{templateID}

成功时返回 204 No Content。

查询构建状态

请求路径

GET /templates/{templateID}/builds/{buildID}/status

请求参数

参数名称	参数类型	必填	描述
logsOffset	integer	否	构建日志起始偏移量
limit	integer	否	返回日志数量
level	string	否	日志级别过滤

响应字段

字段名称	字段类型	描述
templateID	string	模板 ID
buildID	string	构建 ID
status	string	构建状态
reason	string	构建状态原因
logs	string[]	构建日志
logEntries	array	结构化构建日志

查询构建日志

请求路径

GET /templates/{templateID}/builds/{buildID}/logs

请求参数

参数名称	参数类型	必填	描述
cursor	integer	否	日志游标
limit	integer	否	返回日志数量
direction	string	否	日志读取方向
level	string	否	日志级别过滤
source	string	否	日志来源过滤

响应字段

字段名称	字段类型	描述
logs	array	结构化构建日志

通过别名查询模板

请求路径

GET /templates/aliases/{alias}

路径参数

参数名称	参数类型	必填	描述
alias	string	是	模板别名

响应字段

字段名称	字段类型	描述
templateID	string	模板 ID
public	boolean	模板是否公开

请求示例

curl -X GET "$QINIU_SANDBOX_API_URL/templates/base" \
  -H "X-API-Key: $QINIU_API_KEY"

相关文档

• API 概述
• 沙箱模板
• 构建模板