本章将介绍
makers.deployments 上的部署、等待、列出、查询和构建日志方法。一次部署表示把一份待部署内容发布到某个项目的生产环境或预览环境。数据模型
deployments.deploy、deployments.wait 与 deployments.get 返回部署对象，deployments.list 与 deployments.listAll 返回部署对象的集合。deployments.getLog 只返回构建日志地址。字段 | 类型 | 必有 | 说明 |
deploymentId/deployment_id | string/str | 是 | 部署 ID |
projectId/project_id | string/str | 是 | 项目 ID |
env | "Production" | "Preview" | 是 | 部署环境，分别对应生产环境和预览环境 |
status | string/str | 否 | 部署状态。终态取值为 Success、Failed、Timeout、Cancelled 和 Invalid。未到达终态时先为 Pending，随后为 Process |
previewUrl/preview_url | string/str | 否 | 预览链接。可在浏览器中打开的地址仅由 deployments.wait 在 Success 时返回 |
code | string/str | 否 | 部署失败时的错误码 |
createdOn/created_on | string/str | 否 | 创建时间，格式为 ISO 8601 |
modifiedOn/modified_on | string/str | 否 | 修改时间，格式为 ISO 8601 |
deployments.deploy
发起一次部署，待部署内容由
artifact 指定。env 取 "Preview" 而项目尚无生产环境部署时，在发请求前抛出 ValidationError。默认不等待部署完成，调用成功后立即返回，返回结果中不含预览链接。需要预览链接时，可以传入
wait 为 true，也可以在调用返回后单独调用 deployments.wait。等待过程为同步阻塞，方法在部署到达终态或等待超时之前不会返回。参数
参数 | 类型 | 必填 | 说明 |
projectId/project_id | string/str | 是 | 项目 ID |
artifact | Artifact/dict | 是 | 待部署内容 |
env | "Production" | "Preview" | 否 | 部署环境。取 "Preview" 时要求项目已有生产环境部署，默认 "Production" |
wait | boolean/bool | 否 | 是否等待部署到达终态，默认 false |
timeout | number/float | 否 | 最长等待时间，单位为秒，默认 900 |
pollInterval/poll_interval | number/float | 否 | 轮询间隔，单位为秒，默认 5 |
onUploadProgress/upload_progress | 回调 | 否 | 待部署内容上传完成后触发一次 |
onStatusChange/status_change | 回调 | 否 | 部署状态变更时触发，仅 wait 为 true 时生效 |
返回值
Promise<Deployment>/dict —— 未等待时只包含 deploymentId、projectId 和 env 三个字段，其余字段不存在。SDK 不会为补齐这些字段而额外发起查询。示例
const deployment = await makers.deployments.deploy({projectId: "your-project-id",artifact: { files: { "index.html": "<h1>Hello</h1>" } },});console.log(deployment.deploymentId, deployment.env);
deployment = makers.deployments.deploy(project_id="your-project-id",artifact={"files": {"index.html": "<h1>Hello</h1>"}},)print(deployment["deployment_id"], deployment["env"])
待部署内容的形式
artifact 的三种形式互斥，每次调用只能传入其中一种。形式 | 类型 | 说明 |
files | Record<string, string | Uint8Array>/dict[str, str | bytes] | 以键值对形式直接给出文件内容，由 SDK 在内存或临时目录中打包为 Zip。键为相对 POSIX 路径，值支持文本与二进制内容 |
directory | string/str | 本地目录路径，由 SDK 打包为 Zip |
archive | string/str | 本地 Zip 文件路径，通过安全校验后原样上传 |
directory 的常见取值有三类：1. 应用源码所在的项目根目录，例如
"."。2. 静态构建产物目录，例如
"./dist"。该目录的根目录需包含 index.html 作为站点入口，否则访问站点首页时返回 404。SDK 不校验这一点，更多信息请参见 直接上传。3. 本地执行
edgeone makers build 后的产物目录 "./.edgeone"。示例
// 以下四种写法分别对应一种待部署内容，实际调用时只取其中一种await makers.deployments.deploy({projectId: "your-project-id",artifact: { directory: "." },});// artifact: { directory: "./dist", excludePatterns: ["**/*.map"] }// artifact: { directory: "./.edgeone" }// artifact: { archive: "./site.zip" }
# 以下四种写法分别对应一种待部署内容，实际调用时只取其中一种makers.deployments.deploy(project_id="your-project-id",artifact={"directory": "."},)# artifact={"directory": "./dist", "exclude_patterns": ["**/*.map"]}# artifact={"directory": "./.edgeone"}# artifact={"archive": "./site.zip"}
打包规则
传入
directory 时，SDK 按以下规则打包：默认忽略以点开头的文件与目录，
.well-known 和 .edgeone 除外。因此 .git、.env 、.github、.vscode 等目录同样不会进入压缩包。默认还忽略任意层级的
node_modules、打包根目录下的 .edgeone，以及以 .log、.tmp、.temp、.swp、.swo 结尾的文件和 .DS_Store、Thumbs.db、desktop.ini。打包
"./.edgeone" 时忽略规则不同：只忽略 .git，node_modules 与点开头的目录都会保留。此时按 EdgeOne CLI 的产物布局打包，其余目录则把内容置于压缩包根目录。SDK 不读取
.gitignore，默认忽略项无法关闭，只能通过 excludePatterns/exclude_patterns 追加。该参数使用相对压缩包根目录的 POSIX glob 语义，不支持以 ! 开头的取反规则。拒绝符号链接。
传入
archive 时，SDK 在上传前校验压缩包内容，并拒绝包含绝对路径、重复路径或符号链接条目的压缩包。校验通过后原样上传，不重新打包。进度回调
onUploadProgress/upload_progress 在待部署内容上传完成后触发一次。onStatusChange/status_change 在首次查询部署状态时以及之后每次状态变更时触发，首次触发时 previousStatus/previous_status 为空。状态变更回调依赖等待过程，只有传入
wait 为 true 时才会触发。wait 为 false 时 SDK 不查询部署状态，该回调不会被调用，也不会有任何提示。此时如需接收状态变更事件，请把回调传给 deployments.wait。事件 | 字段 |
上传进度事件 | uploadedBytes/uploaded_bytes、totalBytes/total_bytes、completedFiles/completed_files、totalFiles/total_files |
状态变更事件 | deployment（当前部署对象）、previousStatus/previous_status（上一个状态，首次触发时为空） |
注意：
回调抛出异常时不会中断部署。若初始化
Makers 时传入了 logger，异常由 logger 报告；未传入 logger 时该异常被忽略。示例
const result = await makers.deployments.deploy({projectId: "your-project-id",artifact: { files: { "index.html": "<h1>Hello</h1>" } },wait: true,onUploadProgress: (event) => {console.log(event.uploadedBytes, event.totalBytes);},onStatusChange: (event) => {console.log(event.previousStatus, event.deployment.status);},});if (result.status === "Success") {console.log(result.previewUrl);}
result = makers.deployments.deploy(project_id="your-project-id",artifact={"files": {"index.html": "<h1>Hello</h1>"}},wait=True,upload_progress=lambda event: print(event["uploaded_bytes"], event["total_bytes"]),status_change=lambda event: print(event["previous_status"], event["deployment"]["status"]),)if result.get("status") == "Success":print(result.get("preview_url"))
deployments.wait
轮询指定部署直至到达终态。终态取值为
Success、Failed、Timeout、Cancelled 和 Invalid。默认最长等待 15 分钟，每 5 秒轮询一次。部署失败通过返回的
status 表示，不抛出异常。只有本地等待超时或请求本身出错时才抛出异常。参数
参数 | 类型 | 必填 | 说明 |
projectId/project_id | string/str | 是 | 项目 ID |
deploymentId/deployment_id | string/str | 是 | 部署 ID |
timeout | number/float | 否 | 最长等待时间，单位为秒，默认 900 |
pollInterval/poll_interval | number/float | 否 | 轮询间隔，单位为秒，默认 5 |
onStatusChange/status_change | 回调 | 否 | 部署状态变更时触发 |
返回值
Promise<Deployment>/dict —— status 为终态取值之一。status 为 Success 时，previewUrl/preview_url 为可访问的站点地址。注意：
等待超时抛出
DeploymentTimeoutError。该异常只表示本地停止等待，Makers 上的部署仍在继续，SDK 不会取消它。示例
const result = await makers.deployments.wait({projectId: "your-project-id",deploymentId: "your-deployment-id",timeoutMs: 900000,pollIntervalMs: 5000,});if (result.status === "Success") {console.log(result.previewUrl);} else {console.error(result.status, result.code);}
result = makers.deployments.wait(project_id="your-project-id",deployment_id="your-deployment-id",timeout=900,poll_interval=5,)if result.get("status") == "Success":print(result.get("preview_url"))else:print(result.get("status"), result.get("code"))
deployments.list
分页列出指定项目的部署。
参数
参数 | 类型 | 必填 | 说明 |
projectId/project_id | string/str | 是 | 项目 ID |
status | string[]/list[str] | 否 | 按部署状态过滤 |
timeRange/time_range | { start, end }/dict | 否 | 按创建时间过滤，起止时间格式为 ISO 8601 |
repoBranch/repo_branch | string[]/list[str] | 否 | 按代码分支过滤 |
page | number/int | 否 | 页码，从 0 开始，默认 0 |
pageSize/page_size | number/int | 否 | 每页条数，取值范围为 1 至 100，默认 20 |
order.field | string/str | 否 | 排序字段。两种语言的取值不同，TypeScript 为 "createdOn" 或 "modifiedOn"，Python 为 "created_on" 或 "modified_on" |
order.direction | "asc" | "desc" | 否 | 排序方向 |
返回值
Promise<Page<Deployment>>/dict —— 包含 items、page、pageSize/page_size、total 和 hasNext/has_next 五个字段。页码从 0 开始。
示例
const page = await makers.deployments.list({projectId: "your-project-id",page: 0,pageSize: 20,order: { field: "createdOn", direction: "desc" },});console.log(page.total, page.hasNext);for (const deployment of page.items) {console.log(deployment.deploymentId, deployment.status);}
page = makers.deployments.list(project_id="your-project-id",page=0,page_size=20,order={"field": "created_on", "direction": "desc"},)print(page["total"], page["has_next"])for deployment in page["items"]:print(deployment["deployment_id"], deployment["status"])
deployments.listAll / deployments.list_all
列出指定项目的全部部署。过滤与排序参数与
deployments.list 相同，但不接受 page。参数
参数 | 类型 | 必填 | 说明 |
projectId/project_id | string/str | 是 | 项目 ID |
status | string[]/list[str] | 否 | 按部署状态过滤 |
timeRange/time_range | { start, end }/dict | 否 | 按创建时间过滤，起止时间格式为 ISO 8601 |
repoBranch/repo_branch | string[]/list[str] | 否 | 按代码分支过滤 |
pageSize/page_size | number/int | 否 | 每页条数，取值范围为 1 至 100，默认 20 |
order.field | string/str | 否 | 排序字段。两种语言的取值不同，TypeScript 为 "createdOn" 或 "modifiedOn"，Python 为 "created_on" 或 "modified_on" |
order.direction | "asc" | "desc" | 否 | 排序方向 |
返回值
AsyncIterable<Deployment>/Iterator[dict] —— 由 SDK 自动翻页。示例
for await (const deployment of makers.deployments.listAll({projectId: "your-project-id",})) {console.log(deployment.deploymentId, deployment.status);}
for deployment in makers.deployments.list_all(project_id="your-project-id"):print(deployment["deployment_id"], deployment["status"])
deployments.get
按项目 ID 和部署 ID 查询单个部署。部署不存在时抛出
NotFoundError。参数
参数 | 类型 | 必填 | 说明 |
projectId/project_id | string/str | 是 | 项目 ID |
deploymentId/deployment_id | string/str | 是 | 部署 ID |
返回值
Promise<Deployment>/dict —— 其中的 previewUrl/preview_url 未经签名，需要可访问的站点地址时请使用 deployments.wait。示例
const deployment = await makers.deployments.get({projectId: "your-project-id",deploymentId: "your-deployment-id",});console.log(deployment.status, deployment.env);
deployment = makers.deployments.get(project_id="your-project-id",deployment_id="your-deployment-id",)print(deployment["status"], deployment["env"])
deployments.getLog / deployments.get_log
查询指定部署的构建日志地址。
参数
参数 | 类型 | 必填 | 说明 |
projectId/project_id | string/str | 是 | 项目 ID |
deploymentId/deployment_id | string/str | 是 | 部署 ID |
返回值
Promise<GetLogResult>/dict —— 只包含 logUrl/log_url。示例
const { logUrl } = await makers.deployments.getLog({projectId: "your-project-id",deploymentId: "your-deployment-id",});console.log(logUrl);
result = makers.deployments.get_log(project_id="your-project-id",deployment_id="your-deployment-id",)print(result["log_url"])
