自定义 API · 使用说明（小白向）

本文说明：服务器管理 → 自定义 API 怎么用——配置表格化输出、发布、试调，以及用户后端如何对接。
适合：项目管理员、业务配置、用户项目后端开发。
关联：服务配置-使用说明 · 数据模型-使用说明 · sdk/使用文档

---

阅读建议

你是谁	建议先看
平台配置员	第 3～6 章（新建、输出组装、发布）
用户后端	第 2 章架构 → 第 7 章调用流程
和动态 API 选型	第 1.2 对比表
401 / 403	第 9 章 FAQ

---

1. 一句话

自定义 API = 在天幕里配置「查哪些表、怎么嵌套、入参是什么」，发布后对外提供 一条固定 HTTP 接口（/yc/custom-api/v1/{projectId}/{apiKey}），
适合 复杂查询、1:N:N 嵌套 JSON、多表组装，而不是单表 CRUD。

1.1 和动态 API 怎么选？

	动态 API	自定义 API
来源	数据模型 发布 自动生成	手工 新建 并配置输出
典型场景	单表增删改查	订单+明细+商品一次查出
路径	.../dynamic-api/v1/.../{modelKey}/list 等	.../custom-api/v1/.../{apiKey}
配置位置	数据模型 → 发布	自定义 API 编辑器
鉴权	服务配置（项目级）	服务配置 + 接入与安全

简单 CRUD 用动态 API；要多表嵌套、自定义入参/出参结构用自定义 API。

---

2. 接入架构（用户后端必读）

用户浏览器 / 小程序
    │  用户登录 JWT（你们自己的）
    ▼
用户后端 BFF（你们的服务，如 :4000）
    │  ① X-Access-Key → 换短期 Token
    │  ② Authorization: Bearer → 调 custom-api
    ▼
天幕平台  /yc/custom-api/v1/{projectId}/{apiKey}

禁止把 YC_ACCESS_KEY、接入密钥写进前端或 App 包体。

---

3. 入口与列表

路径：项目 → 服务器管理 → 自定义 API

列 / 操作	说明
API 名称	展示名
API 标识 apiKey	运行面 URL 路径段，英文，项目内唯一
处理器类型	见第 4 章
状态	草稿 / 已发布
新建	打开编辑抽屉
试调	填 body 测返回
发布 / 下线	仅已发布可被外部调用
接入与安全	对外开关、密钥、IP、env 模板

---

4. 处理器类型

类型	说明	何时用
输出组装	表格配置输出块、接口参数，支持 1:N:N 嵌套	最常用；复杂查询
模型代理	代理某数据模型动态 API	快速包一层动态 API
编排引用	调用已发布 API 编排	逻辑已在编排里做好

下文以 输出组装 为主。

---

5. 新建自定义 API（输出组装）

5.1 基本信息

字段	说明
API 名称	如 商品列表（含分类）
API 标识 apiKey	如 goods-with-category，发布后勿随意改
HTTP 方法	多为 POST
描述	可选

5.2 输出组装 Tab（可视化）

1. 接口参数：定义调用方传入的 params、分页 currentPage / pageSize 等。
2. 输出块：按表/模型添加块，配置字段、别名、嵌套子块（1:N）。
3. 参与表对应的数据模型须 已绑定连接 且建议 已发布动态 API（便于试调与权限一致）。
4. 关系图里配好的 出站关系 可用于嵌套结构。

5.3 配置 / JSON Tab

高级用户可直接编辑 definition_json；与可视化需保持一致。
改完保存前可在 试调 验证。

5.4 保存与发布

1. 确定 保存 → 状态一般为 草稿。
2. 列表 发布 → 已发布。
3. 复制 请求地址（相对路径 /yc/custom-api/v1/...）对照 env。

---

6. 试调

1. 列表点 试调（或编辑内试调）。
2. 请求体示例：

{
  "params": {
    "status": "1"
  },
  "currentPage": 1,
  "pageSize": 10
}

3. 控制台试调可能自动带 跳过鉴权 头；不能当作生产方案。
4. 真实对外是否 401，请用 Postman 或 BFF 按第 7 章测。

---

7. 用户后端对接

7.1 平台管理员要先做的

步骤	操作
1	自定义 API 发布，记下 apiKey
2	服务配置-使用说明 开启 运行时鉴权
3	自定义 API 接入与安全：生成密钥、开 对外接入、配 IP 白名单（推荐）
4	复制 env 模板 发给后端

交给后端的信息：

项	示例
YC_BASE_URL	https://api.example.com/yc
YC_PROJECT_ID	服务配置页项目 ID
YC_ACCESS_KEY	ycak_... 一次性密钥
apiKey	goods-list

7.2 调用流程

1. BFF 校验 你们自己的 用户登录态。
2. 若无有效平台 Token，则：
   POST {YC_BASE_URL}/custom-api/v1/{YC_PROJECT_ID}/_auth/token
   请求头：X-Access-Key: {YC_ACCESS_KEY}
   Body 可选：{ "ttlSeconds": 600 }
3. 业务请求：
   POST {YC_BASE_URL}/custom-api/v1/{YC_PROJECT_ID}/{apiKey}
   请求头：Authorization: Bearer {accessToken}
   Body：与试调一致。

7.3 使用 SDK（推荐）

见 sdk/使用文档 §4.4、§6：

import { createClientFromEnv } from 'yc-runtime-sdk';
const yc = createClientFromEnv();
const data = await yc.custom.invoke('goods-list', {
  params: { userId: 1 },
  currentPage: 1,
  pageSize: 10,
});

YC_ACCESS_KEY 与动态 API 换 Token 机制在统一鉴权下 共用 服务配置凭证（详见 SDK 文档）。

---

8. 接入与安全弹窗

配置	说明
对外接入	关=运行面可不强制 Token（不推荐生产）
生成 / 轮换密钥	ycak_... 仅展示一次
Token 有效期	默认 600s，最长 3600s
IP 白名单	BFF 出口 IP，每行一条
复制 env 模板	一键生成 .env 示例

密钥在平台 哈希存储，不会明文回显；轮换后旧 Key 失效。

---

9. 常见问题（FAQ）

9.1 未发布能调吗？

不能。 须列表状态 已发布。

9.2 试调通、Postman 401？

试调可能跳过鉴权；对外须 Access-Key 换 Token 或检查服务配置总开关。

9.3 输出为空 / 缺嵌套？

• 参与模型是否已发布、连接是否正确。
• 接口参数是否与输出块筛选条件匹配。
• 关系图 N:N 中间表是否配置完整。

9.4 apiKey 能改吗？

已发布后改 key 会导致旧 URL 失效；应新建 API 或走版本策略。

9.5 和 API 编排一起用？

处理器选 编排引用，或编排 HTTP 节点调 custom-api；见 API编排-使用说明。

9.6 动态 API 和自定义 API 密钥一样吗？

项目级鉴权在 服务配置 统一；
自定义 API 列表另有 接入与安全 生成 接入密钥（ycak_），与动态 API 的 ycdk_ 生成入口可能不同，均以页面展示为准，一并交给 BFF 环境变量。

---

10. 推荐阅读顺序

1. 连接配置-使用说明
2. 数据模型-使用说明
3. 服务配置-使用说明
4. 本文
5. sdk/使用文档

---

修订记录

版本	日期	说明
v1.0	2026-05-22	初版：自定义 API 控制台 + 用户后端对接