API 编排 · 使用说明（小白向）

本文说明：服务器管理 → API 编排 怎么用——用可视化流程组合多个 HTTP 调用，对外只暴露一条接口。
适合：需要聚合接口、透传第三方、减少前端多次请求的开发与配置人员。
关联：数据模型-使用说明 · 自定义API-使用说明

---

阅读建议

你是谁	建议先看
第一次用	第 2 章概念 → 第 4 章 5 分钟上手
要调动态 API	第 6 章 HTTP 节点 + 数据模型发布
表达式不会写	第 7 章 {{...}}
节点报错	第 9 章 FAQ + 第 8 章可用节点

---

1. 一句话

API 编排 = 在平台里画一条「先 A 再 B 再拼结果」的流程；
调用方只请求 一个编排标识，平台在后台按步骤执行并返回最终 JSON。

前端 / BFF  ──►  一条编排接口  ──►  平台按 steps 执行  ──►  合并后的 data

---

2. 名词解释

名词	说明
编排	一条完整流程定义，含 steps、output
编排标识	英文 key，如 httpbin-demo；调用 URL 用它
草稿 / 已发布	只有 已发布 才能被正式 invoke
试运行	不发布也可测，传入 input JSON
steps	步骤数组，按顺序执行
input	调用方传入的 JSON 根对象，表达式里 {{input.xxx}}
variables	流程内常量，如 API 根地址
definition_json	存库的完整定义（可视化与 JSON Tab 同步）
invoke	对外执行编排的 HTTP 接口

---

3. 入口

路径：项目 → 服务器管理 → API 编排

列表操作：新建编排、编辑、试运行、发布、下线。

编辑窗 Tab：流程设计 | JSON | 使用文档（内置说明）。

---

4. 五分钟上手（HTTPBin 演示）

步骤 1：新建

新建编排 → 全屏编辑窗打开。

步骤 2：顶栏必填

字段	示例	说明
编排名称	HTTPBin 演示	展示用
编排标识	httpbin-demo	英文+数字+中划线，项目内唯一
HTTP 方法	POST	与对外调用一致
触发路径	可留空	一般自动生成

步骤 3：看默认流程

画布默认：

开始 → HTTP 请求 → 数据转换 → 结束

• HTTP 请求 https://httpbin.org/get?uid={{input.userId}}
• 转换 取出 origin、url 等写入 response
• 结束 按全局 output 返回

点节点 → 右侧 节点配置 修改。

步骤 4：保存

点 确定 → 存为 草稿。

步骤 5：试运行

列表 → 试运行 → 入参：

{
  "userId": "demo"
}

成功可见 httpbin 返回数据经转换后的 body。

步骤 6：发布与调用

1. 列表 发布。
2. 调用（需登录 Token + projectId）：

POST /yc/server-manage/api-orchestrations/invoke/httpbin-demo?projectId=你的项目ID
Content-Type: application/json
Authorization: Bearer <JWT>

{
  "userId": "demo"
}

成功：code: 200，data.body 为编排输出。

对外生产：也可将编排 引用 到 自定义 API（编排引用） 或 服务配置 鉴权后的运行面路径，按项目实际部署为准；管理端 invoke 适合联调。

---

5. 编辑界面三栏

区域	作用
左：节点库	点击添加节点；标「规划中」的暂不可执行
中：画布	拖拽、连线；自动排列 纵向整理
右：节点配置	选中节点后编辑 URL、映射等

全局输出 Tab：设置 bodyPath（如 response）、statusCode。

---

6. 与动态 API 配合（推荐）

动态 API 是单表 CRUD；编排负责组合。

需求	做法
用户 + 订单一起返回	编排里两个 HTTP 步骤，分别调用户/订单动态 API
只查子表列表	不必编排，直接调子表 POST .../list
写多表	编排里顺序多个 HTTP create

调动态 API 的 HTTP 节点示例：

POST {{variables.apiBase}}/dynamic-api/v1/{{variables.projectId}}/products/list

Body：

{
  "currentPage": 1,
  "pageSize": 10,
  "params": { "user_id": "{{input.userId}}" }
}

variables 在 JSON 根级定义 apiBase、projectId；路径后缀以 数据模型发布配置 为准（默认 /list）。

鉴权：若项目开启运行面鉴权，HTTP 节点请求头加 Authorization: Bearer ...（或由 BFF 换 Token 后调用）。

---

7. 表达式 {{...}}

写法	含义
{{input.userId}}	试运行 / invoke 传入的字段
{{variables.apiBase}}	根级 variables
{{steps.http1.response.body.id}}	名为 http1 的步骤响应体字段

可用于：URL、Body、转换映射。

---

8. 当前可执行节点

节点 type	作用
start	入口标记
end	提前结束，按 output 返回
http	发 HTTP 请求
transform	字段映射、组装对象
delay	延迟毫秒

暂不可执行（可拖入设计，运行会提示）：SQL、模型实体、Redis、分支、循环、并行等——以编辑器「节点库」标注为准。

---

9. 新增一步怎么做？

1. 左侧点 HTTP 请求 / 数据转换。
2. 画布连线：上一步底部 → 新节点顶部。
3. 选中新节点，右侧填配置。
4. （可选）点 同步 JSON。
5. 保存。

顺序：以 steps 数组顺序为准，应与画布逻辑一致；复杂调整可直接改 JSON Tab。

---

10. 双 HTTP 聚合示例（思路）

需求：先查用户，再查订单，合并返回。

1. variables：apiBase、projectId
2. steps：
   • http getUser → 用户动态 API /get?id=...
   • http getOrders → 订单 /list，params 里 user_id={{steps.getUser.response.body.id}}
   • transform → mapping 拼 { user, orders }，outputPath: response
3. output.bodyPath: response

字段名以真实模型与命名策略为准。

---

11. 常见问题（FAQ）

11.1 试运行成功，invoke 404？

• 是否 发布。
• 编排标识 是否与 URL 一致。
• projectId query 是否正确。

11.2 HTTP 步骤 401？

动态 API 开了鉴权 → HTTP 节点要带 Token，或从 BFF 调用。

11.3 模型实体节点报错？

该节点 尚未支持执行；请改用 HTTP 调动态 API。

11.4 改完流程外部没变？

草稿需 发布 后生效；已发布可 重新发布（若产品提供）或再次发布。

11.5 和自定义 API 区别？

	API 编排	自定义 API
侧重	步骤流、多 HTTP 组合	表格化输出、1:N 嵌套、QueryPlan
配置	画布 / JSON steps	输出块 + 接口参数
对外	invoke / 引用	/yc/custom-api/v1/{projectId}/{apiKey}

两者可 编排引用 自定义 API，见 自定义API-使用说明。

---

12. 推荐阅读顺序

1. 数据模型-使用说明（先发布动态 API）
2. 本文
3. 自定义API-使用说明（复杂查询输出）

---

修订记录

版本	日期	说明
v1.0	2026-05-22	初版：API 编排小白向使用说明