调用方式

调用方先按标识取得服务地址,再向该地址发起业务请求。寻址请求与业务请求分开,寻址结果只包含端点、记录版本与授权信息;业务结果由目标 Agent 返回,平台不代替处理,也不保存业务正文。调用方保存记录编号,便于核对。

调用步骤

寻址只解决找到目标的问题,业务请求仍需按目标端点的协议发起。两步分开记录,出现问题时可以判断是身份、寻址还是业务环节的原因;调用方保存记录编号,便于后续核对。

寻址与业务请求使用不同的记录。寻址记录说明是否找到目标,业务记录由目标 Agent 维护;两边都保留时,便于判断失败发生在哪一步。

  1. 提交 Agent 标识、调用方标识与凭据。
  2. 取得端点、记录版本与可用字段。
  3. 按端点协议发起业务请求。
  4. 保存记录编号与业务结果。

请求与返回字段

请求字段说明需要返回的内容,返回字段说明寻址结果。字段范围与授权范围相关,超出范围的部分不返回;字段不一致时按调用错误核对,不通过重复请求尝试取得未授权内容。

字段方向说明
Agent 标识请求目标 Agent
调用方标识请求发起调用的主体
凭据请求调用方身份证明
请求字段请求需要返回的字段
端点返回目标服务地址
记录版本返回目标当前版本
记录编号返回本次寻址记录编号

超时与重试

寻址请求超时后,先按记录编号核对是否已经处理,再决定是否重新发起。业务请求的超时与重试由调用方按业务规则处理,不以寻址记录代替业务结果;重复发起前应确认上一次请求的状态,避免同一业务被处理多次。

业务侧需要幂等时,由调用方与目标 Agent 约定。平台只记录寻址与调用状态,不判断业务是否重复,也不回滚业务结果。

超时并不等同于失败,可能只是返回未及时到达。先查记录再决定重试,可以减少重复处理;业务侧需要幂等时,由调用方与目标约定识别方式。

端点与缓存

端点可能因迁移、扩容或回调调整而变化。长期缓存旧端点会导致请求失败,也会让记录与实际调用不一致;需要缓存时设置核对机制,按记录版本判断是否需要刷新。

端点缓存时间越长,端点调整后的失败范围越大。按记录版本核对,可以在不频繁请求的前提下保持端点可用。

  • 端点变化后重新寻址,不继续使用旧地址。
  • 按记录版本判断端点是否为当前版本。
  • 回调地址变化后按新地址重新核对可达性。
  • 缓存端点时设置核对机制,不长期保存。
  • 记录编号与端点在排查时一并提供。

记录核对

每次寻址返回记录编号,调用记录保存记录编号、调用方、目标、状态与时间。出现争议时按编号查询,核对请求时间与结果,判断问题出在寻址还是业务环节;查询范围按接入约定执行。

记录只用于核对请求与排查,不用于评价 Agent 效果。需要对外说明调用情况时,按记录编号与时间范围整理,不导出业务正文。

遇到错误

按接入、鉴权、寻址、调用、记录五类判断错误,并按排查顺序核对标识、凭据与端点。

查看错误与排查