六维教程

EdgeOne Makers API Token

前面讲的都是在控制台网页上操作，或者用 EdgeOne Makers CLI 与本地开发 在命令行里操作。但如果你想把 EdgeOne Makers 集成到自己的系统里，比如公司内部的平台、自动化工具、监控脚本，就得用 API 了。

用 API 得有凭证，这就是 API Token 的作用。这篇讲讲怎么创建 Token、管理权限、调用 API。

什么是 API Token

API Token 就是一串字符串，相当于你的 API 钥匙。调用 EdgeOne Makers 的 API 时，带上这个 Token，平台就知道你是谁、有没有权限操作。

e1_t_abc123def456ghi789jkl012mno345pqr678stu901

Token 以 e1_t_ 开头，后面跟一串随机字符。保管好这个 Token，不要泄露出去，拿到 Token 的人就能以你的身份调用 API。

创建 Token

步骤一: 进入设置页

登录 EdgeOne Makers 控制台，点击右上角的头像，选择”账户设置”。

步骤二: 找到 API Token 管理

在左侧菜单找到”API Tokens”或者”访问令牌”，点击进入。

步骤三: 创建新 Token

点击”创建 Token”按钮，填写以下信息:

字段 说明 示例
Token 名称 给 Token 起个名字，方便识别 my-ci-token
描述 可选，写一下这个 Token 用来干什么 用于 GitHub Actions 自动部署
过期时间 可选，设置 Token 什么时候失效 2027-01-01
权限范围 选择这个 Token 能操作哪些资源 全部项目，或者指定项目

步骤四: 复制保存

创建成功后，页面会显示完整的 Token 字符串。这时候一定要复制保存下来，因为离开这个页面后就看不到完整内容了。

建议把 Token 存到密码管理器里，不要放在代码仓库或者聊天工具里。

权限配置

Token 不是万能的，你可以限制它的权限范围。

权限类型

权限 说明
读取项目 查看项目列表、项目详情、部署记录
管理项目 创建、编辑、删除项目
触发部署 手动触发部署、回滚
管理环境变量 添加、修改、删除环境变量
管理域名 绑定、解绑自定义域名
管理团队成员 邀请、移除团队成员

权限范围

可以选择 Token 作用于哪些项目:

范围 说明
全部项目 Token 能操作账号下所有项目
指定项目 Token 只能操作选中的几个项目
单个项目 Token 只能操作一个项目

最佳实践

实践 说明
最小权限 只给需要的权限，不给多余的
定期轮转 每隔一段时间更换 Token
设置过期时间 给 Token 设一个失效日期
分场景创建 不同用途用不同的 Token

比如 CI/CD 用一个只读和触发部署权限的 Token，监控脚本用一个只读权限的 Token，管理工具用一个全权限的 Token。

调用 API

有了 Token 就可以调用 API 了。EdgeOne Makers 的 API 是 RESTful 风格的 HTTP 接口。

基础地址

https://api.edgeone.ai/v1

认证方式

在请求头里带上 Token:

Authorization: Bearer e1_t_abc123def456ghi789jkl012mno345pqr678stu901

API 调用示例

获取项目列表

curl -X GET "https://api.edgeone.ai/v1/projects" \
  -H "Authorization: Bearer e1_t_abc123def456ghi789jkl012mno345pqr678stu901"

返回:

{
  "data": [
    {
      "id": "proj_abc123",
      "name": "my-blog",
      "status": "active",
      "url": "https://my-blog.edgeone.app",
      "created_at": "2026-08-01T10:00:00Z"
    },
    {
      "id": "proj_def456",
      "name": "my-portfolio",
      "status": "active",
      "url": "https://my-portfolio.edgeone.app",
      "created_at": "2026-08-05T14:30:00Z"
    }
  ]
}

获取项目详情

curl -X GET "https://api.edgeone.ai/v1/projects/proj_abc123" \
  -H "Authorization: Bearer e1_t_abc123def456ghi789jkl012mno345pqr678stu901"

返回:

{
  "data": {
    "id": "proj_abc123",
    "name": "my-blog",
    "status": "active",
    "framework": "vue",
    "build_command": "npm run build",
    "output_directory": "dist",
    "url": "https://my-blog.edgeone.app",
    "created_at": "2026-08-01T10:00:00Z",
    "updated_at": "2026-08-18T09:00:00Z"
  }
}

触发部署

curl -X POST "https://api.edgeone.ai/v1/projects/proj_abc123/deploy" \
  -H "Authorization: Bearer e1_t_abc123def456ghi789jkl012mno345pqr678stu901" \
  -H "Content-Type: application/json" \
  -d '{"branch": "main"}'

返回:

{
  "data": {
    "deployment_id": "d-xyz789",
    "status": "queued",
    "created_at": "2026-08-18T10:00:00Z"
  }
}

获取部署列表

curl -X GET "https://api.edgeone.ai/v1/projects/proj_abc123/deployments" \
  -H "Authorization: Bearer e1_t_abc123def456ghi789jkl012mno345pqr678stu901"

返回:

{
  "data": [
    {
      "id": "d-xyz789",
      "status": "success",
      "trigger": "api",
      "branch": "main",
      "created_at": "2026-08-18T10:00:00Z",
      "completed_at": "2026-08-18T10:02:00Z"
    }
  ]
}

管理环境变量

添加环境变量:

curl -X POST "https://api.edgeone.ai/v1/projects/proj_abc123/env" \
  -H "Authorization: Bearer e1_t_abc123def456ghi789jkl012mno345pqr678stu901" \
  -H "Content-Type: application/json" \
  -d '{"key": "API_KEY", "value": "secret123", "type": "runtime"}'

获取环境变量列表:

curl -X GET "https://api.edgeone.ai/v1/projects/proj_abc123/env" \
  -H "Authorization: Bearer e1_t_abc123def456ghi789jkl012mno345pqr678stu901"

错误处理

API 调用可能返回各种错误码:

状态码 含义 常见原因
400 请求参数错误 缺少必填字段、参数格式不对
401 未认证 Token 缺失或无效
403 权限不足 Token 没有对应的操作权限
404 资源不存在 项目 ID 或部署 ID 不对
409 冲突 资源已存在，比如项目名重复
429 请求太频繁 触发了速率限制
500 服务器内部错误 平台自身的问题，稍后重试

错误响应的格式:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API token"
  }
}

速率限制

API 有调用频率限制，避免滥用:

接口类型 限制
读取类接口 每分钟 60 次
写入类接口 每分钟 30 次
部署接口 每分钟 10 次

如果触发限制，会返回 429 状态码。遇到这种情况，等一会儿再重试。

可以在响应头里看到剩余配额:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1692345600

Token 管理

查看 Token 列表

在账户设置页可以看到所有 Token 的列表，包括名称、创建时间、最后使用时间、过期时间。

吊销 Token

如果 Token 泄露或者不用了，要及时吊销。

在 Token 列表里找到要吊销的 Token，点击”吊销”按钮。吊销后这个 Token 就失效了，不能再用来调用 API。

Token 轮转

定期更换 Token 是个好习惯。

步骤:

  1. 创建一个新的 Token
  2. 把系统里的旧 Token 替换成新 Token
  3. 测试新 Token 能正常工作
  4. 吊销旧 Token

这样就不会有服务中断的风险。

SDK

如果用的是 JavaScript/TypeScript，可以用官方提供的 SDK，比直接调 API 更方便:

npm install @edgeone/sdk

使用示例:

const EdgeOne = require('@edgeone/sdk');

const client = new EdgeOne({
  token: 'e1_t_abc123def456ghi789jkl012mno345pqr678stu901'
});

async function main() {
  // 获取项目列表
  const projects = await client.projects.list();
  console.log(projects);

  // 触发部署
  const deployment = await client.deployments.create({
    projectId: 'proj_abc123',
    branch: 'main'
  });
  console.log(deployment);
}

main();

SDK 封装了认证、错误处理、分页等逻辑，用起来比直接写 curl 方便。

速查卡片

要点 说明
API Token 是什么 调用 API 的凭证，类似密码
创建方式 账户设置 > API Tokens > 创建 Token
权限配置 可以限制操作类型和资源范围
认证方式 请求头 Authorization: Bearer {token}
API 基础地址 https://api.edgeone.ai/v1
错误码 401 未认证，403 权限不足，429 请求过频
速率限制 读取 60 次/分，写入 30 次/分，部署 10 次/分
Token 管理 定期轮转，泄露及时吊销，按用途分 Token
上一篇
EdgeOne Makers CLI 与本地开发
下一篇
EdgeOne Makers 消息通知