启动构建草稿
OpenAPI 契约
- 方法
- POST
- 路径
/api/v1/builds/{taskId}/start- 认证
- jwtBearer (bearer) OR automationKey (bearer)
- 响应状态
- 202 400 401 402 403 404 409 413 429 500
请求与响应 Schema
JSON
{
"requestBody": {},
"responses": {
"202": {
"description": "Build accepted",
"content": {
"application/json": {
"$ref": "#/components/schemas/CompileTaskResponse"
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"$ref": "#/components/schemas/RequestError"
}
}
},
"401": {
"description": "Authentication required or invalid",
"content": {
"application/json": {
"$ref": "#/components/schemas/SecurityError"
}
}
},
"402": {
"description": "Insufficient NCU balance",
"content": {
"application/json": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"403": {
"description": "Authenticated but not permitted",
"content": {
"application/json": {
"$ref": "#/components/schemas/SecurityError"
}
}
},
"404": {
"description": "Requested build was not found",
"content": {
"application/json": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"409": {
"description": "Request conflicts with current build state",
"content": {
"application/json": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"413": {
"description": "Upload or expanded archive exceeds a configured limit",
"content": {
"application/json": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"429": {
"description": "HTTP rate limit or API-key NCU usage limit exceeded",
"content": {
"application/json": {
"$ref": "#/components/schemas/RateLimitError"
}
}
},
"500": {
"description": "Unexpected server error",
"content": {
"application/json": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}使用 JWT 或带 build:write 的 nfy_ 密钥启动一个仍待处理且未启动的草稿。访问草稿本身要求对其项目拥有有效 build:write，legacy/ad-hoc 草稿则要求 exact ownership。解析出的项目也要求有效 build:write，并且必须属于 active workspace。提供 projectId，或省略该参数但继承草稿中已保存的项目时，automation key 还需要 project:write；只要提供 processorId，还需要 processor:read。这是非幂等 POST：启动后重复调用不是安全重试。请轮询原操作返回的任务 URL。
服务会重新检查已保存的输入，并逐字段应用配置。请求中的 projectId 优先于草稿项目；若未提供，则保留草稿项目。平台按请求值、解析后的项目默认值、服务回退值依次取值。功能按请求值、所提供的处理器预设、解析后的项目默认值、服务回退值依次取值。请求中的 processorId 会替换草稿处理器值。skipIrOpt 来自本次启动请求。提供 hostingPath 会替换草稿路径；省略则保留原路径。
草稿必须仍为待处理且未启动。输入丢失、无效配置、缺少 project capability、归档 workspace、并发限制、额度不足或容量不足都会阻止转换。