处理阶段
一次请求从提交开始,经过格式与状态校验、授权判断,再返回结果并写入记录。阶段按顺序执行,前一阶段不通过时不进入下一阶段。
请求进入解析节点后,先判断字段是否齐全,再核对标识格式和记录状态。校验不通过时直接返回错误,不进入授权判断。
- 提交:携带标识、调用方标识和凭据。
- 校验:检查字段完整性、标识格式和记录状态。
- 授权:按调用方标识确定可见字段和可用节点。
- 返回:输出端点、版本、状态和权属摘要。
- 记录:写入请求编号、调用方、结果和失败原因。
请求字段
请求字段以解析所需为限。调用方不提交业务正文,也不提交与本次解析无关的主体信息。
凭据随请求提交,不放在地址参数中。调用方标识应与凭据所属主体一致,不一致时按无权限处理。
| 字段 | 必填 | 说明 |
|---|---|---|
| 标识 | 是 | 待解析的完整标识 |
| 调用方标识 | 是 | 已登记的主体或节点标识 |
| 凭据 | 是 | 接入时签发的调用凭据 |
| 请求字段 | 否 | 指定需要的返回字段,缺省返回基础字段 |
| 请求编号 | 否 | 调用方生成的幂等编号,长度不超过 64 位 |
返回字段
成功返回包含标识、记录版本、端点、状态、权属摘要和记录编号。失败返回错误码、错误说明和记录编号,不返回端点。
返回字段按授权范围裁剪。调用方请求超出范围的字段时,接口拒绝请求,不返回部分结果。
| 返回项 | 内容 | 说明 |
|---|---|---|
| 标识 | 本次解析对象 | 与请求标识一致 |
| 记录版本 | 当前版本号 | 变更后递增 |
| 端点 | 地址、协议、接入方式 | 仅在解析成功时返回 |
| 权属摘要 | 主体名称与授权范围 | 按授权范围返回 |
| 记录编号 | 本次请求记录编号 | 用于核对与排查 |
错误分类
错误按原因分类,调用方按类型处理,不对同一错误连续重试。
错误说明用于定位原因,调用方按说明核对字段和权限,不把错误说明直接展示给最终用户。
| 错误类型 | 处理方式 |
|---|---|
| 格式错误 | 核对标识和字段格式后重新提交 |
| 标识不存在 | 停止请求,核对标识来源 |
| 无权限 | 检查调用方标识和授权范围 |
| 记录校验失败 | 暂停使用结果,联系登记节点 |
| 版本不一致 | 等待节点同步后重新解析 |
幂等与版本协商
调用方可为同一次业务请求生成请求编号,重复提交时按请求编号识别,避免重复写入记录。请求编号由调用方生成,长度不超过 64 位。
涉及接口字段调整时,按版本协商处理。调用方在接入测试阶段确认字段含义和返回方式,正式使用后按当前版本处理,不混用旧字段。
请求编号相同的重复提交,按首次结果返回,不重复写入记录。调用方在超时后重试时沿用原请求编号,避免产生多条记录。