调用步骤
寻址只解决找到目标的问题,业务请求仍需按目标端点的协议发起。两步分开记录,出现问题时可以判断是身份、寻址还是业务环节的原因;调用方保存记录编号,便于后续核对。
寻址与业务请求使用不同的记录。寻址记录说明是否找到目标,业务记录由目标 Agent 维护;两边都保留时,便于判断失败发生在哪一步。
- 提交 Agent 标识、调用方标识与凭据。
- 取得端点、记录版本与可用字段。
- 按端点协议发起业务请求。
- 保存记录编号与业务结果。
请求与返回字段
请求字段说明需要返回的内容,返回字段说明寻址结果。字段范围与授权范围相关,超出范围的部分不返回;字段不一致时按调用错误核对,不通过重复请求尝试取得未授权内容。
| 字段 | 方向 | 说明 |
|---|---|---|
| Agent 标识 | 请求 | 目标 Agent |
| 调用方标识 | 请求 | 发起调用的主体 |
| 凭据 | 请求 | 调用方身份证明 |
| 请求字段 | 请求 | 需要返回的字段 |
| 端点 | 返回 | 目标服务地址 |
| 记录版本 | 返回 | 目标当前版本 |
| 记录编号 | 返回 | 本次寻址记录编号 |
超时与重试
寻址请求超时后,先按记录编号核对是否已经处理,再决定是否重新发起。业务请求的超时与重试由调用方按业务规则处理,不以寻址记录代替业务结果;重复发起前应确认上一次请求的状态,避免同一业务被处理多次。
业务侧需要幂等时,由调用方与目标 Agent 约定。平台只记录寻址与调用状态,不判断业务是否重复,也不回滚业务结果。
超时并不等同于失败,可能只是返回未及时到达。先查记录再决定重试,可以减少重复处理;业务侧需要幂等时,由调用方与目标约定识别方式。
端点与缓存
端点可能因迁移、扩容或回调调整而变化。长期缓存旧端点会导致请求失败,也会让记录与实际调用不一致;需要缓存时设置核对机制,按记录版本判断是否需要刷新。
端点缓存时间越长,端点调整后的失败范围越大。按记录版本核对,可以在不频繁请求的前提下保持端点可用。
- 端点变化后重新寻址,不继续使用旧地址。
- 按记录版本判断端点是否为当前版本。
- 回调地址变化后按新地址重新核对可达性。
- 缓存端点时设置核对机制,不长期保存。
- 记录编号与端点在排查时一并提供。
记录核对
每次寻址返回记录编号,调用记录保存记录编号、调用方、目标、状态与时间。出现争议时按编号查询,核对请求时间与结果,判断问题出在寻址还是业务环节;查询范围按接入约定执行。
记录只用于核对请求与排查,不用于评价 Agent 效果。需要对外说明调用情况时,按记录编号与时间范围整理,不导出业务正文。