文档开发者接入

第三方应用接入与连接器规范

约定认证、字段映射、工具副作用、错误处理和连接生命周期。

目录、配置与授权是不同状态

当前实现区分可连接、已停用、未配置、待校验和不可用等状态;管理员的供应商配置、个人或组织账号授权、任务工具授权还需分别验证。开发源码中有 Gmail 只读配置路径,但这不证明所有部署已启用,也不表示同类应用都能直接连接。

连接器应描述什么

连接器的交付材料应让管理员判断它能读什么、写什么、在哪里运行,以及如何停用。以下是接入说明字段建议,不是当前产品可直接导入的 manifest。

连接器交付说明
项目应包含
身份与版本唯一标识、维护者、兼容版本与支持联系人
认证OAuth / 密钥方式、权限范围、有效期与撤销
能力工具名、输入输出、只读或写入、所需审批
数据字段映射、时区、分页、保留与模型暴露范围
运行限流、超时、幂等、健康检查和故障恢复

凭据只进入受控配置

客户端展示连接状态和脱敏标识,密钥不得放进任务正文、知识文档或应用 manifest。OAuth 的授权范围和回调地址按供应商要求配置;刷新、到期、撤销及配置变更后重新校验。当前供应商配置实现包含草稿、检查和发布步骤,不能把格式检查等同于账号已经授权。

读操作与写操作分别验收

先以一个只读对象验证字段、分页、时间范围和数据完整性。写入类工具应明确目标、预览、批准主体和重复调用处理,并从外部系统回执确认最终状态。第三方权限撤销后,正在排队的任务也要在执行前重新校验。

处理外部系统的不确定性

对限流按服务返回的等待提示退避,设定重试上限。网络超时后先查询原操作结果,不能直接重复建单或发送。字段变化、分页截断和授权不足应显式报错,输出中标明数据完整性和抓取时间,避免把部分结果当成完整业务事实。

连接上线与停用

交付测试矩阵、授权台账、版本清单、运行手册和回退步骤。上线后指定账号与适配代码维护者;停用时停止新调用、处理未完成任务、撤销凭据,并按数据约定清理缓存和测试副本。兼容性变化通过版本或变更说明通知项目负责人。

返回全部文档下一篇指南

还有疑问?

查看专家支持