
五步接入
五步顺序固定,每一步都有对应的确认结果。完成联调后再切换正式凭据,可以避免测试流量进入正式环境,也便于在正式启用前发现端点、字段与错误返回方面的问题。
- 自助注册:提交开发者主体、联系人与用途说明。
- 创建 Agent:填写名称、能力说明、服务端点与回调地址。
- 配置沙箱:取得沙箱凭据,配置测试端点与回调。
- 联调测试:完成一次沙箱调用,核对返回字段、记录版本与错误说明。
- 切换正式:生成正式凭据,停用沙箱凭据,启用正式标识。
提交材料
材料用于核对接入主体与 Agent 用途,内容应当与实际上线情况一致。材料不齐时会被退回补充,补齐后继续办理;登记信息发生变化时按变更事项更新,不重复提交整套材料。
材料中的端点、协议与字段应与实际环境一致,回调地址需要能够接收验证。授权范围按调用方分别说明,避免用一份宽范围授权覆盖多个用途。
- 主体名称与联系人信息。
- Agent 名称、用途与能力说明。
- 服务端点、协议类型与调用说明。
- 输入输出字段与错误返回。
- 授权对象、字段范围与期限。
沙箱联调
沙箱用于验证端点、回调与错误返回。开发者用沙箱凭据完成一次调用,核对返回字段、记录版本与错误说明,确认调用方能按标识取得端点,并确认授权范围与请求字段一致。
联调阶段不使用正式凭据,也不把沙箱凭据用于正式流量。测试完成后停用沙箱凭据,再切换正式凭据;沙箱阶段的调用记录保留,可用于对照正式启用后的返回结果。
联调时按正常调用与错误调用各核对一次,确认成功返回与失败提示都能被调用方识别。发现字段不一致时先修正登记或请求,不通过反复重试掩盖问题。
切换正式
| 变化 | 办理事项 | 是否重新接入 |
|---|---|---|
| 端点变化 | 提交端点变更,核对回调与协议 | 否 |
| 能力说明变化 | 更新能力说明与字段 | 否 |
| 授权范围变化 | 提交授权调整,由目标主体确认 | 否 |
| 联系人变化 | 更新联系人信息 | 否 |
| Agent 注销 | 提交注销说明,开发者凭据同时停用 | 是,标识不复用 |
变更与注销
正式标识启用后,端点、能力说明、授权范围与联系人变化通过变更事项更新,标识保持不变。变更形成新的记录版本,调用方重新寻址即可取得当前端点,不需要修改调用方保存的标识。
注销需要提交说明。注销后标识不复用,相关开发者凭据同时停用;停用与恢复的操作会写入记录,恢复后版本递增。凭据遗失或泄露时停用并重建,不尝试找回原值。
变更与注销都会形成记录,调用方可以按记录版本判断当前状态。维护人变化时同步更新联系人,避免通知与处置无人承接。