开发者文档中心

OpenAPI进入控制台

服务端 API 与回调 · 2026-10-31

服务端 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-api-read-example.mjsJavaScript
/** 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.
使用流程预览 · 示意图

帮助理解此示例的使用顺序,不执行代码或验证连接。

  1. 准备

    从下载中心取得 developer-client.mjs,与本示例放在同一目录。 先确认自己的 tenantId、真实 agentId 及 agent-versions.read 授权;由受控服务端代码显式调用导出函数,不在浏览器运行。

  2. 在项目中使用

    server-api-read-example.mjs · 服务端模块示例

  3. 核对结果

    最多一次权限预检与一次只读 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 前主动降速。

codeHTTP含义处理方式
INVALID_REQUEST400请求参数、查询或正文不符合网关要求按错误说明修正后再提交;不要原样重试。
ACTION_MISMATCH400正文 action 与所调用操作固定的 action 不一致省略 action,或使用操作文档中的固定值。
QUERY_MISMATCH400查询参数试图覆盖操作的固定查询删除该查询参数;需要其他分支时改用对应操作。
IDEMPOTENCY_KEY_INVALID400写请求缺少 Idempotency-Key 或格式无效提供 8–100 位字母、数字、下划线、连字符、点或冒号。
API_KEY_INVALID401缺少 Bearer 密钥,或密钥不存在、已到期、已撤销核对 Authorization 请求头与密钥有效期;必要时由管理员创建新密钥。
API_KEY_OWNER_INACTIVE401创建密钥的管理员账号已停用、移出企业或变更身份由当前企业管理员重新创建密钥。
API_KEY_ROTATED401请求执行期间密钥被轮换用新密钥读回业务结果后再决定是否重试。
API_KEY_SITE_MISMATCH403密钥不属于当前站点域名使用创建密钥时的站点地址作为 YUNFU_BASE_URL。
ORIGIN_NOT_ALLOWED403请求携带了与站点不同源的 Origin从服务端调用并去掉浏览器 Origin;密钥不得在浏览器中使用。
ACCOUNT_PERMISSION_DENIED403密钥所属账号已不具备该操作所需权限由企业管理员恢复账号权限,或改用其权限范围内的操作。
TENANT_DISABLED403密钥所属企业已停用联系平台方恢复企业后再调用。
OPERATION_NOT_GRANTED403密钥未勾选该操作调用 GET /v1/capabilities 核对 allowedOperations;需要时创建包含该操作的新密钥。反复调用未授权操作会触发请求防护。
OPERATION_NOT_FOUND404操作 ID 不存在按接口参考核对操作 ID 的拼写与大小写。
METHOD_NOT_ALLOWED405HTTP 方法与操作不符按 Allow 响应头使用 GET 或 POST。
REQUEST_TIMEOUT408读取请求正文超时或被取消检查网络后用原幂等键重试。
IDEMPOTENCY_KEY_REUSED409同一幂等键被用于不同的操作、查询或正文重试保持原请求完全一致;新的业务提交使用新键。
REQUEST_IN_PROGRESS409同一幂等键的原请求仍在执行按 Retry-After 等待后用原键重试,或在调用记录中按 requestId 核对。
REQUEST_OUTCOME_UNKNOWN409原请求中断,执行结果未知先读取业务数据确认是否生效;确认未生效后才用新键重新提交。
REPLAY_UNAVAILABLE409原请求已完成,但响应超过缓存上限或已过 24 小时原请求不会再次执行;通过业务读取操作获取结果。
ORIGINAL_KEY_ROTATED409原请求由轮换前的密钥发起,不重放旧回执用当前密钥读回业务结果,不换键强行重做。
PAYLOAD_TOO_LARGE413请求正文超过该操作的大小上限缩小正文,或使用该业务的分批导入操作。
UNSUPPORTED_MEDIA_TYPE415POST 未使用 application/json设置 Content-Type: application/json 并发送 JSON 正文。
RATE_LIMITED429超过密钥的每分钟调用限额按 Retry-After 等待到下一分钟窗口;可用 X-RateLimit-Remaining 提前降速。
API_BUSY429超过短时突发或并发上限(也可能以 503 返回)降低并发,按 Retry-After 退避;写入用原幂等键重试。
REQUEST_BLOCKED429账号因高频、重复越权或连续协议错误被临时封禁停止调用直到 blockedUntil;修正调用方后再恢复,换密钥不能解除。
MFA_REQUIRED403企业强制 MFA,当前不允许 API Key 机器接入联系企业管理员确认接入方案;重新登录或轮换密钥无效。
SERVICE_UNAVAILABLE503操作处理器暂不可用稍后重试;写入用原幂等键。
INTERNAL_ERROR503服务内部异常,正文含排查编号 reference只读可有界重试;写入先核对业务结果,并向支持提供 reference。

按接口选择分页方式

不要为所有接口统一添加 page/pageSize。下面的操作先要求出现在当前密钥的 allowedOperations 中;日志入口则使用后台登录会话。保持每页的筛选与排序,游标只能使用服务端实际返回值。

场景读取入口参数与返回何时结束
智能体版本agent-versions.read?agentId=YOUR_AGENT_ID&page=0page 从 0 开始;固定每页 30 条。读取 entries / total / page,不能自行加入 pageSize 改变大小。page × 30 + entries.length ≥ total 时结束;legacy 是兼容历史列表,单独处理。
文本会话记录conversations.read?page=1&pageSize=20page 从 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.mjs
  • sdk/server-api-read-example.mjs
  • app/v1/operations/developer-gateway.ts
  • backend/services/developer-api/developer-capabilities.ts
  • app/api/agent-versions/route.ts
  • database/stores/conversations/conversation-records.ts
  • database/stores/developer-store.ts

文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。