服务端 SDK、分页与失败恢复
用当前服务端 SDK 先核对企业和授权,再完成一次只读调用;区分 HTTP、传输异常及业务结果。
运行示例前准备
从下载中心取得服务端开发客户端和只读示例,放在同一目录。示例是 JavaScript ES 模块,宿主需支持 fetch、Response、AbortSignal.any 与 AbortSignal.timeout;仅在受控服务端显式调用导出函数。先通过只读权限预检确认本人的企业编号,准备已授权的 agentId 与 agent-versions.read。示例不会自动创建或扩大密钥权限。
完整服务端只读示例
运行前
server-api-read-example.mjs · 服务端模块示例
- 从下载中心取得 developer-client.mjs,与本示例放在同一目录。
- 先确认自己的 tenantId、真实 agentId 及 agent-versions.read 授权;由受控服务端代码显式调用导出函数,不在浏览器运行。
完整代码 · 47 行
/** Server-only, read-only example. Import and call explicitly; loading this file performs no request. */
import {YunfuDeveloperClient, YunfuApiError} from './developer-client.mjs';
export async function readFirstAgentVersions({baseUrl,apiKey,agentId,expectedTenantId,fetch,signal,timeoutMs=15000}) {
if(typeof agentId!=='string'||!agentId.trim())throw new Error('Provide your authorized agentId');
if(typeof expectedTenantId!=='string'||!expectedTenantId.trim())throw new Error('Confirm expectedTenantId from your authorized preflight');
const transport=fetch||globalThis.fetch;
const guardedFetch=signal ? (url,options)=>transport(url,{...options,signal:options?.signal?AbortSignal.any([signal,options.signal]):signal}) : transport;
const client=new YunfuDeveloperClient({baseUrl,apiKey,fetch:guardedFetch,timeoutMs});
let stage='capabilities',requestId=null;
try {
if(signal?.aborted)return {outcome:'cancelled',stage};
const grants=await client.capabilities();
requestId=grants.requestId;
if(grants.tenantId!==expectedTenantId)return {outcome:'tenant-mismatch',stage};
if(signal?.aborted)return {outcome:'cancelled',stage};
if(!grants.allowedOperations.includes('agent-versions.read'))return {outcome:'not-granted',stage};
stage='read';requestId=null; // A preflight ID is not a business-request ID.
// request() retains headers and response type. For a known JSON operation, json() is also available.
const response=await client.request('agent-versions.read',{query:{agentId,page:0},signal});
requestId=response.headers.get('x-request-id');
const contentType=response.headers.get('content-type')||'';
if(!contentType.includes('application/json')){
await response.body?.cancel().catch(()=>{});
return {outcome:'unexpected-content-type',stage,requestId};
}
const data=await response.json();
if(!Array.isArray(data?.entries)||!Number.isSafeInteger(data.total)||!Number.isSafeInteger(data.page))
return {outcome:'invalid-response',stage,requestId};
return {outcome:'ok',requestId,data};
} catch(error) {
if(error instanceof YunfuApiError)return {
outcome:'http-error',stage,status:error.status,requestId:error.requestId,retryAfter:error.retryAfter,
...(error.status===403&&error.body?.code==='MFA_REQUIRED'&&error.body.loginUrl===null?{code:'MFA_REQUIRED',loginUrl:null}:{}),
};
if(signal?.aborted||error?.name==='AbortError')return {outcome:'cancelled',stage,requestId};
if(error?.name==='TimeoutError')return {outcome:'timeout',stage,requestId};
return {outcome:'transport-or-response-error',stage,requestId};
}
}
// In your authorized server job, pass environment-managed credentials and a real agentId:
// const result = await readFirstAgentVersions({baseUrl:process.env.YUNFU_BASE_URL,
// apiKey:process.env.YUNFU_API_KEY,agentId:process.env.YUNFU_AGENT_ID,
// expectedTenantId:process.env.YUNFU_TENANT_ID});
// Inspect result.outcome explicitly. Do not log credentials, full response bodies or customer data.
// This example performs at most one preflight and one GET. It does not retry, create, publish or bill a voice call.使用流程预览 · 示意图
帮助理解此示例的使用顺序,不执行代码或验证连接。
- 准备
从下载中心取得 developer-client.mjs,与本示例放在同一目录。 先确认自己的 tenantId、真实 agentId 及 agent-versions.read 授权;由受控服务端代码显式调用导出函数,不在浏览器运行。
- 在项目中使用
server-api-read-example.mjs · 服务端模块示例
- 核对结果
最多一次权限预检与一次只读 GET;按 outcome 区分权限、HTTP、取消/超时和响应类型,不自动重试或执行写入。
预期结果:最多一次权限预检与一次只读 GET;按 outcome 区分权限、HTTP、取消/超时和响应类型,不自动重试或执行写入。
按 outcome 处理结果
ok 返回业务数据和可用的请求编号;not-granted / tenant-mismatch 停在预检,不发送业务读取。http-error 包含 HTTP 状态和可用的 requestId / retryAfter;MFA_REQUIRED 不通过登录或换密钥绕过。cancelled / timeout / transport-or-response-error 属于取消、超时或传输/解析问题,不伪装成 HTTP 错误。unexpected-content-type / invalid-response 不猜测字段。
request() 返回原生 Response,适合需要响应头、流式或下载的调用;json() 仅适用于确定返回 JSON 的操作。不要把服务端 YunfuApiError 与访客 SDK 的 YunfuError/pending 混为一套错误协议。示例不自动重试,也不把 GET 示例改成写入。
HTTP 状态与处理方式
以下为常见状态,具体接口可能只返回其中部分;业务状态和 HTTP 状态需要分别核对。
有 X-Request-Id 时,由有权的管理员在请求日志核对;提前拒绝的请求可能没有编号,此时记录时间、操作路径和状态。/v1/capabilities 的编号不进入业务日志。错误正文按接口解析,不依赖错误文案自动重试。
| 状态 | 含义 | 处理方式 |
|---|---|---|
| 400 | 参数错误 | 按当前操作检查字段、格式和固定参数;修正后再提交。 |
| 401 | 凭据失效 | 检查密钥是否过期、撤销或轮换,以及站点是否匹配。 |
| 402 | 余额或额度不足 | 核对余额、套餐和接待额度;恢复可用后再确认是否提交。 |
| 403 | 权限或来源不符 | 核对操作授权、账号权限和请求来源;不要关闭认证绕过。 |
| 404 | 资源不存在或不可见 | 核对路径、资源编号和所属企业。 |
| 405 | 请求方法不符 | 按该操作文档和 Allow 响应头使用 GET 或 POST。 |
| 408 | 读取请求超时 | 检查网络和正文上传;写入重试前核对原结果并保留原幂等键。 |
| 409 | 版本、幂等或状态冲突 | 先读回业务结果;有 Retry-After 时等待。修改配置先合并最新版本,结果未知不换键重做。 |
| 413 | 请求过大 | 按接口限制缩小请求或使用该业务提供的分批导入入口。 |
| 415 | 正文格式不支持 | 开放网关 POST 使用 Content-Type: application/json 和有效 JSON 正文。 |
| 422 | 业务条件不满足 | 按错误提示补齐配置或业务状态;不要重复提交相同无效请求。 |
| 429 | 调用限流 | 按 Retry-After 等待,降低调用频率;写入重试仍使用原幂等键。 |
| 503 | 依赖不可用 | 稍后核对服务状态;只读可有界重试,写入先确认原结果。 |
网关错误码
网关自身的拒绝(认证、授权、限流、幂等、格式)在 JSON 正文中返回稳定的 code,按 code 分支处理,不要解析 error 文案。没有 code 的错误由业务接口返回,按该接口说明处理。每次响应都带 X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset,可在收到 429 前主动降速。
| code | HTTP | 含义 | 处理方式 |
|---|---|---|---|
| INVALID_REQUEST | 400 | 请求参数、查询或正文不符合网关要求 | 按错误说明修正后再提交;不要原样重试。 |
| ACTION_MISMATCH | 400 | 正文 action 与所调用操作固定的 action 不一致 | 省略 action,或使用操作文档中的固定值。 |
| QUERY_MISMATCH | 400 | 查询参数试图覆盖操作的固定查询 | 删除该查询参数;需要其他分支时改用对应操作。 |
| IDEMPOTENCY_KEY_INVALID | 400 | 写请求缺少 Idempotency-Key 或格式无效 | 提供 8–100 位字母、数字、下划线、连字符、点或冒号。 |
| API_KEY_INVALID | 401 | 缺少 Bearer 密钥,或密钥不存在、已到期、已撤销 | 核对 Authorization 请求头与密钥有效期;必要时由管理员创建新密钥。 |
| API_KEY_OWNER_INACTIVE | 401 | 创建密钥的管理员账号已停用、移出企业或变更身份 | 由当前企业管理员重新创建密钥。 |
| API_KEY_ROTATED | 401 | 请求执行期间密钥被轮换 | 用新密钥读回业务结果后再决定是否重试。 |
| API_KEY_SITE_MISMATCH | 403 | 密钥不属于当前站点域名 | 使用创建密钥时的站点地址作为 YUNFU_BASE_URL。 |
| ORIGIN_NOT_ALLOWED | 403 | 请求携带了与站点不同源的 Origin | 从服务端调用并去掉浏览器 Origin;密钥不得在浏览器中使用。 |
| ACCOUNT_PERMISSION_DENIED | 403 | 密钥所属账号已不具备该操作所需权限 | 由企业管理员恢复账号权限,或改用其权限范围内的操作。 |
| TENANT_DISABLED | 403 | 密钥所属企业已停用 | 联系平台方恢复企业后再调用。 |
| OPERATION_NOT_GRANTED | 403 | 密钥未勾选该操作 | 调用 GET /v1/capabilities 核对 allowedOperations;需要时创建包含该操作的新密钥。反复调用未授权操作会触发请求防护。 |
| OPERATION_NOT_FOUND | 404 | 操作 ID 不存在 | 按接口参考核对操作 ID 的拼写与大小写。 |
| METHOD_NOT_ALLOWED | 405 | HTTP 方法与操作不符 | 按 Allow 响应头使用 GET 或 POST。 |
| REQUEST_TIMEOUT | 408 | 读取请求正文超时或被取消 | 检查网络后用原幂等键重试。 |
| IDEMPOTENCY_KEY_REUSED | 409 | 同一幂等键被用于不同的操作、查询或正文 | 重试保持原请求完全一致;新的业务提交使用新键。 |
| REQUEST_IN_PROGRESS | 409 | 同一幂等键的原请求仍在执行 | 按 Retry-After 等待后用原键重试,或在调用记录中按 requestId 核对。 |
| REQUEST_OUTCOME_UNKNOWN | 409 | 原请求中断,执行结果未知 | 先读取业务数据确认是否生效;确认未生效后才用新键重新提交。 |
| REPLAY_UNAVAILABLE | 409 | 原请求已完成,但响应超过缓存上限或已过 24 小时 | 原请求不会再次执行;通过业务读取操作获取结果。 |
| ORIGINAL_KEY_ROTATED | 409 | 原请求由轮换前的密钥发起,不重放旧回执 | 用当前密钥读回业务结果,不换键强行重做。 |
| PAYLOAD_TOO_LARGE | 413 | 请求正文超过该操作的大小上限 | 缩小正文,或使用该业务的分批导入操作。 |
| UNSUPPORTED_MEDIA_TYPE | 415 | POST 未使用 application/json | 设置 Content-Type: application/json 并发送 JSON 正文。 |
| RATE_LIMITED | 429 | 超过密钥的每分钟调用限额 | 按 Retry-After 等待到下一分钟窗口;可用 X-RateLimit-Remaining 提前降速。 |
| API_BUSY | 429 | 超过短时突发或并发上限(也可能以 503 返回) | 降低并发,按 Retry-After 退避;写入用原幂等键重试。 |
| REQUEST_BLOCKED | 429 | 账号因高频、重复越权或连续协议错误被临时封禁 | 停止调用直到 blockedUntil;修正调用方后再恢复,换密钥不能解除。 |
| MFA_REQUIRED | 403 | 企业强制 MFA,当前不允许 API Key 机器接入 | 联系企业管理员确认接入方案;重新登录或轮换密钥无效。 |
| SERVICE_UNAVAILABLE | 503 | 操作处理器暂不可用 | 稍后重试;写入用原幂等键。 |
| INTERNAL_ERROR | 503 | 服务内部异常,正文含排查编号 reference | 只读可有界重试;写入先核对业务结果,并向支持提供 reference。 |
按接口选择分页方式
不要为所有接口统一添加 page/pageSize。下面的操作先要求出现在当前密钥的 allowedOperations 中;日志入口则使用后台登录会话。保持每页的筛选与排序,游标只能使用服务端实际返回值。
| 场景 | 读取入口 | 参数与返回 | 何时结束 |
|---|---|---|---|
| 智能体版本 | agent-versions.read?agentId=YOUR_AGENT_ID&page=0 | page 从 0 开始;固定每页 30 条。读取 entries / total / page,不能自行加入 pageSize 改变大小。 | page × 30 + entries.length ≥ total 时结束;legacy 是兼容历史列表,单独处理。 |
| 文本会话记录 | conversations.read?page=1&pageSize=20 | page 从 1 开始,pageSize 为 1–100;读取 conversations / total / page / pageSize。 | page × pageSize ≥ total 时结束。每页 asOf 不是跨页事务快照;保持原筛选与排序。 |
| 后台请求日志 | /api/developer-platform?view=requests | 仅本人有权的后台会话可读;不是 /v1/operations 操作。每页最多 50 条,读取 requests 与 next。 | next 为 null 时结束;否则把 next.before 与 next.beforeId 一起原样带入下一页。 |
幂等冲突和失败恢复
先看 HTTP 状态、可用的 requestId/state 和实际业务状态;不要依赖错误文案字符串作自动重试判断。幂等键允许 8–100 位字母、数字、下划线、连字符、点或冒号。
| 场景 | 含义 | 恢复方式 |
|---|---|---|
| 同一幂等键改了操作、查询或正文 | 409;幂等键在同一个 API Key 记录下跨操作共享,不是每个接口各自独立。 | 先核对原请求。重试必须保持同一操作、查询、正文与键;另一笔已确认业务提交才用另一键。 |
| 密钥已轮换 | 密钥轮换后,旧回执的密钥版本与当前不同时返回 409。 | 用当前获准凭据查询业务并由管理员核对原日志,不以换密钥或换键强行重复执行。 |
| 请求仍在执行或结果未知 | 409 可含 requestId / state,并给 Retry-After: 2;state 可能为 running 或 unknown。 | 等待后读回业务和原请求日志,不把 409 当作执行失败,也不换新键盲重做。 |
| 已完成但不能重放 | 回执完整正文最多缓存 256000 字节、窗口 24 小时;超限、过期或无缓存时不能重放。 | 查询业务结果;缓存过期不表示业务已撤销,也不授权再次执行。Idempotency-Replayed: true 仅表示返回原缓存。 |
| 业务 revision 冲突 | 业务接口也可能返回 409,与网关幂等冲突不同;revision 不是幂等键。 | 先重读并合并他人变更。确认原业务没有完成、形成新的提交内容后,才由用户确认新的逻辑提交与新键。 |
| 429、超时或断流 | 429 按 Retry-After 处理;网络异常、HTTP 状态与业务完成状态是三回事。 | 只读调用可做有界重试;写入先核对原结果。SDK 不自动重试写入,客户端取消也不保证服务端已回滚。 |
请求编号与响应类型
业务网关通常在登记请求后返回 X-Request-Id;方法错误、鉴权失败、参数拒绝或限流可能在登记前发生,不能假定每个业务错误都有编号。/v1/capabilities 独立返回编号但不进入业务请求日志。
普通 JSON、文件、SSE 与 NDJSON 按 Content-Type 分开读取;HTTP 2xx/202 或 api.request.completed 只表示对应 HTTP 处理结果,不代替异步任务、电话或外部投递的最终成功。
在本人有权的“开放平台 → 请求日志”记录时间、operationId、状态、请求编号和脱敏错误。该日志的后台接口不能用 API Key 调用。不要记录认证头、完整票据或客户正文。
实现依据 · 仓库内路径
sdk/developer-client.mjssdk/server-api-read-example.mjsapp/v1/operations/developer-gateway.tsbackend/services/developer-api/developer-capabilities.tsapp/api/agent-versions/route.tsdatabase/stores/conversations/conversation-records.tsdatabase/stores/developer-store.ts
文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。