接入流程

接入按自助注册、创建 Agent、配置沙箱、联调测试、切换正式五步进行。联调通过前只使用沙箱凭据,正式启用后材料变化通过变更事项更新,不需要重新接入,标识保持稳定。五步的确认结果都可以在登记记录中核对。

企业办公区的门禁通道
接入按登记、沙箱、联调和正式启用依次完成

五步接入

五步顺序固定,每一步都有对应的确认结果。完成联调后再切换正式凭据,可以避免测试流量进入正式环境,也便于在正式启用前发现端点、字段与错误返回方面的问题。

  1. 自助注册:提交开发者主体、联系人与用途说明。
  2. 创建 Agent:填写名称、能力说明、服务端点与回调地址。
  3. 配置沙箱:取得沙箱凭据,配置测试端点与回调。
  4. 联调测试:完成一次沙箱调用,核对返回字段、记录版本与错误说明。
  5. 切换正式:生成正式凭据,停用沙箱凭据,启用正式标识。

提交材料

材料用于核对接入主体与 Agent 用途,内容应当与实际上线情况一致。材料不齐时会被退回补充,补齐后继续办理;登记信息发生变化时按变更事项更新,不重复提交整套材料。

材料中的端点、协议与字段应与实际环境一致,回调地址需要能够接收验证。授权范围按调用方分别说明,避免用一份宽范围授权覆盖多个用途。

  • 主体名称与联系人信息。
  • Agent 名称、用途与能力说明。
  • 服务端点、协议类型与调用说明。
  • 输入输出字段与错误返回。
  • 授权对象、字段范围与期限。

沙箱联调

沙箱用于验证端点、回调与错误返回。开发者用沙箱凭据完成一次调用,核对返回字段、记录版本与错误说明,确认调用方能按标识取得端点,并确认授权范围与请求字段一致。

联调阶段不使用正式凭据,也不把沙箱凭据用于正式流量。测试完成后停用沙箱凭据,再切换正式凭据;沙箱阶段的调用记录保留,可用于对照正式启用后的返回结果。

联调时按正常调用与错误调用各核对一次,确认成功返回与失败提示都能被调用方识别。发现字段不一致时先修正登记或请求,不通过反复重试掩盖问题。

切换正式

变化办理事项是否重新接入
端点变化提交端点变更,核对回调与协议否
能力说明变化更新能力说明与字段否
授权范围变化提交授权调整,由目标主体确认否
联系人变化更新联系人信息否
Agent 注销提交注销说明,开发者凭据同时停用是,标识不复用

变更与注销

正式标识启用后,端点、能力说明、授权范围与联系人变化通过变更事项更新,标识保持不变。变更形成新的记录版本,调用方重新寻址即可取得当前端点,不需要修改调用方保存的标识。

注销需要提交说明。注销后标识不复用,相关开发者凭据同时停用;停用与恢复的操作会写入记录,恢复后版本递增。凭据遗失或泄露时停用并重建,不尝试找回原值。

变更与注销都会形成记录,调用方可以按记录版本判断当前状态。维护人变化时同步更新联系人,避免通知与处置无人承接。

下一步

了解 Agent 标识与调用凭据的分工,以及凭据轮换与保管要求。

查看身份与鉴权