概览
安装
TypeScript 运行环境为 Node.js 20+，仅发布 ESM。Python 运行环境为 3.10+。
npm install @edgeone/makers-sdk
pip install makers-sdk
获取 API Token
1. 在控制台创建 API Token，步骤见 API Token。
2. 写入环境变量
MAKERS_API_TOKEN。初始化
import { Makers } from "@edgeone/makers-sdk";const makers = new Makers({token: process.env.MAKERS_API_TOKEN,region: "china",});
import osfrom makers_sdk import Makersmakers = Makers(token=os.environ["MAKERS_API_TOKEN"],region="china",)
region 须与签发该 API Token 的站点一致：中国站用 "china"，国际站用 "global"。若未指定
region，SDK 将依次自动探测中国站（china）与国际站（global），并将结果缓存在当前 Makers 实例中。构造参数
参数名与类型以
TypeScript / Python 的形式给出。参数 | 类型 | 必填 | 默认值 | 说明 |
token | string / str | 是 | - | EdgeOne Makers API Token |
source | string / str | 否 | "sdk" | 请求来源 |
timeout | number / float | 否 | 30 | 单次请求超时，单位为秒 |
retries | number / int | 否 | 3 | 查询类最大重试次数；写操作不重试 |
logger | Logger | 否 | - | 用于输出 SDK 日志。传入带 debug、info、warn、error 方法的对象，未传入时不输出日志 |
公开成员
成员 | 类型 | 说明 |
makers.projects | Projects | 项目与环境变量操作 |
makers.deployments | Deployments | 部署操作 |
makers.tokens | Tokens | 签发租户 token（ tokens.create） |
makers.region | "china" | "global" | 只读。构造时传入的中国站（ china）或国际站（global），未指定时为自动探测结果。 |
类型名为 TypeScript 导出的类型，Python 的对应命名空间不作为公开类型导出。
错误处理
所有错误继承
MakersError，公开字段为 code、cause，以及 requestId / request_id 和 httpStatus / http_status。错误信息在 TypeScript 中通过 error.message获取，在 Python 中通过 str(error)获取。异常类 | 说明 |
AuthError | Token 无效或无权访问 |
ValidationError | 入参不合法或服务端返回校验错误。本地校验在发请求前抛出 |
NotFoundError | 项目或部署不存在 |
ConflictError | 资源冲突，例如项目名称已存在 |
RateLimitError | 触发限流 |
UploadError | 上传制品失败 |
TimeoutError | 单次请求超时 |
DeploymentTimeoutError | 等待部署到达终态超时（继承 TimeoutError） |
import { Makers, MakersError, NotFoundError } from "@edgeone/makers-sdk";const makers = new Makers({token: process.env.MAKERS_API_TOKEN,region: "china",});try {await makers.projects.get({ projectId: "missing" });} catch (error) {if (error instanceof NotFoundError) {console.error(error.code, error.requestId, error.httpStatus);} else if (error instanceof MakersError) {console.error(error.code, error.message, error.requestId);}}
import osfrom makers_sdk import Makers, MakersError, NotFoundErrormakers = Makers(token=os.environ["MAKERS_API_TOKEN"],region="china",)try:makers.projects.get(project_id="missing")except NotFoundError as error:print(error.code, error.request_id, error.http_status)except MakersError as error:print(error.code, str(error), error.request_id)
进阶：签发租户 token
tokens.create 签发租户 token。初始化当前 Makers 时，token 请传入控制台创建的主 API Token（账号级凭证）。SDK 不会检查传入的是否为主 API Token。已签发的租户 token 不支持查询或删除。
调用成功后返回
token、tokenId / token_id 和 expired。expired 为过期时间，格式为 Unix 时间戳（秒）。对同一 tenantId / tenant_id 再次签发时，token 与 tokenId / token_id 不变，expired 可能更新。参数不符合要求时，将在发起请求前抛出 ValidationError。import { Makers } from "@edgeone/makers-sdk";const platform = new Makers({token: process.env.MAKERS_API_TOKEN,region: "china",});const { token, tokenId, expired } = await platform.tokens.create({tenantId: "user-open-id",name: "user-open-id",expiresIn: 86400,});const user = new Makers({token,region: "china",});const { projectId } = await user.projects.create({ name: "my-site" });await user.deployments.deploy({projectId,artifact: { files: { "index.html": "<h1>Hello</h1>" } },});
import osfrom makers_sdk import Makersplatform = Makers(token=os.environ["MAKERS_API_TOKEN"],region="china",)created = platform.tokens.create(tenant_id="user-open-id",name="user-open-id",expires_in=86400,)user = Makers(token=created["token"],region="china",)project = user.projects.create(name="my-site")user.deployments.deploy(project_id=project["project_id"],artifact={"files": {"index.html": "<h1>Hello</h1>"}},)
参数 | 类型 | 必填 | 说明 |
tenantId / tenant_id | string / str | 是 | 租户标识，最长 64 个字符 |
name | string / str | 是 | Token 名称，长度为 1–128 个字符 |
expiresIn / expires_in | number / int | 是 | 有效期，单位为秒，取值范围为 10–315360000 |
