外部连接接入(Connections API)

通过统一的 /api/v2/workspaces/{workspace_id}/connections 接口集中注册数据库、远程 MCP Server、HTTP API、飞书与邮箱连接,实现凭据隔离、按操作审批授权与调用审计。历史独立的第三方 MCP 与数据库连接接口已统一收敛至本接口。

统一模型:metadata + spec + 只写 credentials

Connections API 与 Agent 声明式接口遵循同一套写入契约(RFC 7396 PATCH、整份 PUT + If-Match 乐观锁、?dry_run=true 预演),并在凭据安全上做了严格隔离:

支持的连接类型(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 探测预设) 读取业务邮箱邮件与附件同步

端到端接入流程

  1. 测试连通性(不落库)

    先调用 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}"'"}
      }'
  2. 声明式创建连接(支持 ?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)。

  3. 发现 / 导入操作并配置审批策略

    对远程 MCP 连接调用 POST …/{ref}/operations/discover 拉取远端工具;对 HTTP 连接调用 POST …/{ref}/operations/openapi 批量导入操作。随后用 PATCH …/{ref}/operations/{operation} 逐条控制是否启用、审批状态以及是否需要人工写确认。

  4. 授权并挂载到 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 会直接指出阻断原因:

下一步