服务端认证与首次调用
业务系统通过操作网关访问已授权能力。
准备密钥
- 在「开放平台 → 访问密钥」创建最小权限密钥,设置到期、限流与允许操作。只保存在你自己的服务端环境变量。
- 先调用 GET /v1/capabilities,核对 tenantId、expiresAt 和 allowedOperations;该接口不要求 agents.read 权限。再从返回的授权列表中选择业务操作,核对所需参数与真实返回。
- 写入前读取当前 revision,按接口字段构造请求,再附上稳定 Idempotency-Key。
配置自己的调用环境
YUNFU_BASE_URL 填密钥绑定的完整服务源站,例如 https://service.example.com,不带 /console、/api 或查询参数;OEM 域名必须与创建密钥时一致。本地仅使用 loopback HTTP。YUNFU_API_KEY 通过服务端密钥管理或环境变量注入,不贴进网页、URL、日志或聊天。
第一步:只读权限预检
运行前
终端只读检查 · 命令片段
- 仅在服务端设置 YUNFU_BASE_URL 与 YUNFU_API_KEY;不要放入浏览器控制台。
完整代码 · 2 行
curl --fail-with-body --show-error --max-time 15 --include "${YUNFU_BASE_URL:?Set your service origin}/v1/capabilities" \
-H "Authorization: Bearer ${YUNFU_API_KEY:?Set your server API key}"使用流程预览 · 示意图
帮助理解此示例的使用顺序,不执行代码或验证连接。
- 准备
仅在服务端设置 YUNFU_BASE_URL 与 YUNFU_API_KEY;不要放入浏览器控制台。
- 在项目中使用
终端只读检查 · 命令片段
- 核对结果
成功返回当前企业的 allowedOperations;复制命令不建立连接,未授权操作不会自动开通。
预期结果:成功返回当前企业的 allowedOperations;复制命令不建立连接,未授权操作不会自动开通。
读懂预检结果
| 字段 | 下一步 |
|---|---|
| tenantId | 确认是要接入的企业;不能用请求参数切换其他企业 |
| expiresAt / checkedAt | 毫秒时间戳;确认有效期并安排轮换,结果仅代表本次核验时刻 |
| allowedOperations | 密钥授权与当前账号权限的交集;空列表时先调整授权,不自动扩大权限 |
| X-Request-Id | 保留时间、HTTP 状态和请求编号供排查;不要保留认证头 |
第二步:验证一个真实业务请求
预检只验证当前凭据和权限,不执行模型、发消息、建工单或发布,也不代表资源、套餐、渠道或模型已就绪。选择 allowedOperations 中一个合适的只读接口,在「接口文档」补齐参数后再调用;写接口需另行授权和幂等键。预检共用每分钟限额,但不进入业务请求日志;实际 /v1/operations 调用再到请求日志核对。
不要混用协议
/v1/operations/{operationId} 使用企业 API Key;/api/* 后台路由使用登录会话,写入还要 Origin 及适用的主体范围。访客、评价、分享、电话和机器人回调有各自的凭据。不能把 API Key 直接用于任意 /api 路由。
查找字段与示例
「接口文档」包含已授权操作、真实路由、契约字段和 curl / Java / Go / PHP / Python 示例。OpenAPI 是索引与契约扩展,不是所有领域对象的完整 JSON Schema;不要据此生成严格 DTO 校验器。OAuth Client Credentials 和旧 /v1/conversations REST 别名未实现。
官方原始接入文档
先按云蝠指南完成入口、智能体和服务配置,再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力,不代表云蝠已开放其中全部接口;腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。
- OpenAPI Initiative · OpenAPI Specification 3.1.0 ↗:理解本站 OpenAPI 文件的 schema、安全方案与导入格式;实际云蝠接口、字段和权限仍以本站接口参考为准。
实现依据 · 仓库内路径
app/v1/operations/developer-gateway.tslib/developer-api/developer-operations.tslib/developer-docs/api-manual.ts
文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。