统一模型:metadata + spec + 只写 credentials
Connections API 与 Agent 声明式接口遵循同一套写入契约(RFC 7396 PATCH、整份 PUT + If-Match 乐观锁、?dry_run=true 预演),并在凭据安全上做了严格隔离:
- 凭据只写不回显:
credentials不属于spec,任何读取响应只返回已配置字段名(status.credentials.fields),绝不回显明文密码或 Token。 {connection_ref}支持 ID 或slug:创建时指定组织内唯一的slug(如shop-db),后续路径可直接使用该slug。- 修改连接目标自动清空凭据:通过
PATCH/PUT变更主机地址、URL 或 OAuth 客户端等连接目标时,服务端自动清空旧凭据以防 SSFR/凭据外泄,需通过PUT …/{connection_ref}/credentials重新写入。
支持的连接类型(GET …/connections/providers)
spec.provider |
能力形态 | 操作来源与典型用途 |
|---|---|---|
postgresql / mysql |
进程内 SQL 引擎(带只读/写策略守卫) | 内置 schema_overview、execute_sql 等数据库问数与查询操作 |
mcp / github |
远程 MCP Server(支持先 POST …/mcp/probe 探测) |
通过 POST …/operations/discover 拉取远端工具清单,自动作为 Agent 工具挂载 |
http |
固定目标 HTTP API | 手工定义或通过 POST …/operations/openapi 导入 OpenAPI 规范生成可调用操作 |
feishu |
飞书 / Lark 开放平台(支持 OAuth 回调) | 文档、知识库空间读写与数据源同步 |
email |
IMAP 邮箱(支持 POST …/mail/detect 探测预设) |
读取业务邮箱邮件与附件同步 |
端到端接入流程
-
测试连通性(不落库)
先调用
POST /api/v2/workspaces/{org_id}/connections/test验证地址与凭据可用,凭据不会保存:curl --fail-with-body \ -X POST "${APEMIND_BASE_URL}/api/v2/workspaces/${APEMIND_ORG_ID}/connections/test" \ -H "Authorization: Bearer ${APEMIND_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "spec": { "provider": "postgresql", "config": {"host": "db.internal", "port": 5432, "database": "erp", "username": "readonly", "sslmode": "require"} }, "credentials": {"password": "'"${DB_PASSWORD}"'"} }' -
声明式创建连接(支持
?handoff=true凭据交接)使用
POST /api/v2/workspaces/{org_id}/connections创建连接(可先加?dry_run=true预演):curl --fail-with-body \ -X POST "${APEMIND_BASE_URL}/api/v2/workspaces/${APEMIND_ORG_ID}/connections" \ -H "Authorization: Bearer ${APEMIND_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "metadata": {"slug": "erp-ro", "name": "ERP 只读库", "description": "查询订单与库存"}, "spec": { "provider": "postgresql", "visibility": "restricted", "enabled": true, "config": {"host": "db.internal", "port": 5432, "database": "erp", "username": "readonly", "sslmode": "require"} }, "credentials": {"password": "'"${DB_PASSWORD}"'"} }'如果是由自动化脚本或 Agent 替人类管理员建连接、不希望脚本经手真实密码或 OAuth 授权码,加上查询参数
?handoff=true并留空credentials:服务端会创建连接并在响应中返回completion_url,发给负责人到浏览器安全补填凭据即可(补填前调用返回CONNECTION_CREDENTIALS_REQUIRED)。 -
发现 / 导入操作并配置审批策略
对远程 MCP 连接调用
POST …/{ref}/operations/discover拉取远端工具;对 HTTP 连接调用POST …/{ref}/operations/openapi批量导入操作。随后用PATCH …/{ref}/operations/{operation}逐条控制是否启用、审批状态以及是否需要人工写确认。 -
授权并挂载到 Agent
推荐直接在Agent 声明式配置的
spec.capabilities.connectors.connections中引用连接并限定level与operations(服务端自动同步授权);若需要向成员、角色或服务账号独立授权,也可直接调用PUT …/{ref}/grants/{principal_type}/{principal_id}。
直接调用连接操作与审计查询
除了让 Agent 在对话中自动调用(MCP 模式下通过 list_connections / invoke_connection,或对 mcp/github 连接直接展开为 Agent 工具),外部程序和受管函数也可以复用同一套权限与审计链路直接调用连接:
# 1. 查看当前凭据在该连接下可调用的操作及 input_schema
curl --fail-with-body \
-H "Authorization: Bearer ${APEMIND_API_KEY}" \
"${APEMIND_BASE_URL}/api/v2/workspaces/${APEMIND_ORG_ID}/connections/erp-ro/tools"
# 2. 执行指定操作(遵循连接策略、写操作确认与限流)
curl --fail-with-body \
-X POST "${APEMIND_BASE_URL}/api/v2/workspaces/${APEMIND_ORG_ID}/connections/erp-ro/tools/execute_sql/invoke" \
-H "Authorization: Bearer ${APEMIND_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"arguments": {"sql": "SELECT status, count(*) FROM orders GROUP BY status LIMIT 20"}}'
每次调用都会记录调用者身份、耗时与状态,可通过 GET …/{ref}/invocations 与 GET …/{ref}/invocations/stats 查明明细与统计;删除连接前可调用 GET …/{ref}/dependents 检查仍引用该连接的 Agent 和数据源。
排障:读懂连接 status.conditions
读取连接详情时,关注 status.conditions[] 中的 Ready 条件:当 status: "False" 时,reason 会直接指出阻断原因:
Disabled:连接已被停用(spec.enabled: false)。CredentialsMissing:尚未补全凭据(常见于?handoff=true或修改目标地址后被自动清空)。Unauthorized/ReauthRequired:OAuth 连接尚未授权或授权已失效,需重新发起POST …/{ref}/oauth/start。- 若已挂载的 Agent 报
ConnectorToolsOff或ConnectorOperationUnavailable,对照声明式配置诊断表修复即可。