第三方应用接入与连接器规范
约定认证、字段映射、工具副作用、错误处理和连接生命周期。
目录、配置与授权是不同状态
当前实现区分可连接、已停用、未配置、待校验和不可用等状态;管理员的供应商配置、个人或组织账号授权、任务工具授权还需分别验证。开发源码中有 Gmail 只读配置路径,但这不证明所有部署已启用,也不表示同类应用都能直接连接。
连接器应描述什么
连接器的交付材料应让管理员判断它能读什么、写什么、在哪里运行,以及如何停用。以下是接入说明字段建议,不是当前产品可直接导入的 manifest。
| 项目 | 应包含 |
|---|---|
| 身份与版本 | 唯一标识、维护者、兼容版本与支持联系人 |
| 认证 | OAuth / 密钥方式、权限范围、有效期与撤销 |
| 能力 | 工具名、输入输出、只读或写入、所需审批 |
| 数据 | 字段映射、时区、分页、保留与模型暴露范围 |
| 运行 | 限流、超时、幂等、健康检查和故障恢复 |
凭据只进入受控配置
客户端展示连接状态和脱敏标识,密钥不得放进任务正文、知识文档或应用 manifest。OAuth 的授权范围和回调地址按供应商要求配置;刷新、到期、撤销及配置变更后重新校验。当前供应商配置实现包含草稿、检查和发布步骤,不能把格式检查等同于账号已经授权。
读操作与写操作分别验收
先以一个只读对象验证字段、分页、时间范围和数据完整性。写入类工具应明确目标、预览、批准主体和重复调用处理,并从外部系统回执确认最终状态。第三方权限撤销后,正在排队的任务也要在执行前重新校验。
处理外部系统的不确定性
对限流按服务返回的等待提示退避,设定重试上限。网络超时后先查询原操作结果,不能直接重复建单或发送。字段变化、分页截断和授权不足应显式报错,输出中标明数据完整性和抓取时间,避免把部分结果当成完整业务事实。
连接上线与停用
交付测试矩阵、授权台账、版本清单、运行手册和回退步骤。上线后指定账号与适配代码维护者;停用时停止新调用、处理未完成任务、撤销凭据,并按数据约定清理缓存和测试副本。兼容性变化通过版本或变更说明通知项目负责人。