创建构建草稿
OpenAPI 契约
- 方法
- POST
- 路径
/api/v1/builds/draft- 认证
- jwtBearer (bearer) OR automationKey (bearer)
- 响应状态
- 201 400 401 402 403 404 413 429 500
请求与响应 Schema
JSON
{
"requestBody": {
"multipart/form-data": {
"properties": {
"file": {
"description": "Input JAR or ZIP archive",
"format": "binary",
"type": "string"
}
},
"required": [
"file"
],
"type": "object"
}
},
"responses": {
"201": {
"description": "Draft created",
"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"
}
}
},
"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"
}
}
}
}
}现在上传 .jar 或 .zip，稍后再配置。需要 JWT，或带有 build:write 的 nfy_ 密钥；提供 projectId 时，自动化密钥还需要 project:write。创建草稿会存储并检查输入，但不会预留额度或调度编译。这是非幂等 POST；重试上传会创建另一份草稿。
此阶段仅设置文件、可选项目和可选 hostingPath。提供项目时要求对它拥有有效 build:write capability，归档 workspace 会拒绝草稿。没有项目时，草稿使用调用方的个人 workspace，之后依赖 exact-owner fallback。草稿以待处理状态开始，除非给出自定义路径，否则保留自动生成的默认私有路径。自定义路径绝不是访问控制开关：构建成功后，hosted 获取仍需要 dashboard JWT 或带 artifact:read 的 nfy_ 密钥，并且 project task 需要有效 artifact:output:read，legacy/ad-hoc task 需要 exact ownership。
使用返回的任务标识调用“启动构建草稿”。无效归档输入、不支持的文件名、无效或冲突的路径，以及调用方 writable collaboration boundary 之外的项目都会被拒绝。