Composio Confluence 集成实战：OAuth 配置、账号绑定与页面/附件操作完整指南

Composio Confluence 集成实战OAuth 配置、账号绑定与页面/附件操作完整指南【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio本文基于 Composio 仓库中的 Confluence 公共支持知识docs/kb/articles/toolkits-confluence.md系统讲解如何在 Composio 上接入 Atlassian Confluence从自定义 OAuth 的 scope 对齐、offline_access刷新令牌、redirect URI 一致性到用正确的 connected account 执行工具再到使用CONFLUENCE_GET_PAGE_BY_ID、CONFLUENCE_UPDATE_PAGE、CONFLUENCE_GET_ATTACHMENTS等工具读取、更新页面与下载附件。读完本文你将掌握一套可直接复用的 Confluence 工具集成方案避免 scope 错配、账号 ID 传错、版本号过期等最常见的踩坑点。Confluence OAuth 配置三要素Confluence 属于 Composio 的 OAuth 类认证工具。当你使用自定义 OAuth自带 Atlassian 开发者应用时需要围绕三个关键点做对齐否则会出现OAuth 已成功但工具执行报错的诡异现象。这三要素在 docs/kb/source/toolkits/confluence/public.md 中有完整记载其源头正是你正在阅读的这篇支持知识。1. Scope 必须与端点类型v1/v2对齐核心原则让 Atlassian 自定义 OAuth 的 scope 与 Composio 期望的 scope 保持一致。Confluence 的 Atlassian API 存在经典classic与细分granular两类 scope具体该用哪一类取决于底层 Confluence 端点是 v1 还是 v2v1 端点使用对应的经典classicscope 集合v2 端点使用对应的细分granularscope 集合。如果不加区分地替换 scope——例如把某个无关的空间spacescope 塞进配置里——即使 OAuth 流程本身顺利完成后续执行 Confluence 工具时仍会报错。这类错误尤其隐蔽因为它发生在认证成功之后排查时容易误判为凭据或网络问题实际根因是 scope 与工具所需权限不匹配。最佳实践在创建自定义 auth config 时直接参考当前 auth-config 流程或官方文档给出的默认 scope 清单逐个对齐不要凭经验精简或扩充。2. 需要刷新令牌时务必加offline_access如果 Agent 需要长期运行、令牌过期后自动续期就必须在 auth config 中加入offline_accessscopeoffline_access是 Atlassian OAuth 授予刷新令牌refresh token的关键 scope它让 Composio 能够在访问令牌过期后自动刷新添加时机在 auth config 中配置好offline_access之后需要重新创建一个新的 connected account才能生效存量连接不受影响对已有 auth config 追加offline_access只影响用户重新连接之后新建的连接。也就是说老连接不会自动获得刷新能力必须触发一次重新连接reconnect流程。从实现机制看这符合 Composio 通用认证模型的约定scope 在授权阶段被固化进 token事后修改配置不会回写已签发的令牌。仓库中 连接账户管理 也印证了连接状态与凭据生命周期由 connected account 承载而不是 auth config。3. Redirect URI 必须与 Atlassian 应用完全一致Composio auth config 中配置的 redirect URI回调地址必须与 Atlassian OAuth 应用里登记的 URI逐字符一致正确做法是复制当前 auth-config 流程或当前文档展示的回调地址严禁复用旧版示例中的 legacy v1 或 v3 回调路径——Atlassian 侧注册的必须是新路径否则授权回调会被拒绝或落到错误页面。这条规则与 Composio 自定义 OAuth 的整体要求一致在仪表盘进入Authentication management → Manage authentication with custom credentials创建自定义 auth config 时redirect URI、client ID、client secret 等字段都必须与你的开发者应用严格对应详见 自定义认证配置。选择自带开发者应用自定义 OAuth的典型动机包括需要超出 Composio 默认应用权限的自定义 scopes、需要独立配额避免共享限流、以及白标需求OAuth 同意页显示你的品牌。用正确的账号执行 Confluence 工具传 connected account ID而不是 auth config ID执行 Confluence 工具时connected_account字段必须填连接账户connected accountID绝不能填认证配置auth configID / integration ID。auth config是认证方案模板描述用什么方式认证OAuth、API key 等、用哪个开发者应用、带哪些 scopes它不绑定具体用户connected account是一次真实授权某个用户在某 auth config 下完成授权后产生的具体连接携带该用户专属的 access token / refresh token。工具执行需要的是具体用户的凭据因此必须传 connected account ID。此外还需注意 ID 格式较新的 SDK 版本可能接受 nano ID 形式较旧的 SDK 版本可能要求 UUID 形式。因此使用前务必核对 SDK 版本与期望的 ID 格式避免因格式不符导致账号解析失败。在 Composio 的通用连接管理模型中连接账户管理 提供按 ID 检索连接、按连接执行工具等能力Confluence 即遵循同一套语义。从 MCPlistTools注解读取支持的 scopes对于支持 MCP 部署的场景Confluence 工具所需的 scopes 可以直接从listToolsAPI 响应的annotations字段中读取当你通过 MCP 方式接入 Composio 时工具元数据里会携带认证相关的注解信息解析annotations即可拿到该工具实际需要的 scope 集合用来与自定义 OAuth 中配置的 scope 做比对从源头规避第 1 节提到的 scope 错配问题。这是排查OAuth 成功但工具执行失败类问题时的第一手依据把annotations里声明的 scopes 与 auth config 里授予的 scopes 逐项核对即可。读取与更新 Confluence 页面按页面 ID 获取正文内容使用CONFLUENCE_GET_PAGE_BY_ID工具通过页面 IDpage ID拉取 Confluence 页面内容。这是页面正文body获取场景下 Composio 官方共享支持的工具Agent 拿到页面 ID 后即可调用它读取指定页面的标题与正文为后续分析、总结或改写提供输入。典型的 Agent 调用链示意伪代码体现编排逻辑1. 从需求中提取/检索 Confluence 页面 ID 2. 调用 CONFLUENCE_GET_PAGE_BY_ID(page_id..., connected_account账户ID) 3. 解析返回的页面标题与正文供 LLM 分析更新页面必须先取最新版本号Confluence 的页面更新是版本敏感的更新操作要求提交正确的页面版本号version版本不匹配会被服务端拒绝。因此官方支持方案要求把两个工具配对使用CONFLUENCE_GET_PAGE_VERSIONS先获取页面当前的最新版本号CONFLUENCE_UPDATE_PAGE再携带该版本号执行更新。编排规则默认行为Agent 应基于最新版本进行更新特例仅当用户明确要求更新到某一特定版本时才使用指定的版本号。这条先查版本、再写页面的顺序是并发编辑场景下的防冲突手段多个 Agent 或协作者同时改同一个页面时只有拿到最新版本才能避免覆盖他人刚提交的内容。正确的调用链1. CONFLUENCE_GET_PAGE_VERSIONS(page_id...) → 得到当前最新 version 2. CONFLUENCE_UPDATE_PAGE(page_id..., version最新版本, body...) 3. 可选再次 GET_PAGE_BY_ID 校验更新结果下载 Confluence 附件下载附件是一个两步流程核心是先取 ID、再下载列出附件调用CONFLUENCE_GET_ATTACHMENTS获取指定页面或空间下的附件列表从返回结果中拿到目标附件的 attachment ID下载文件把上一步得到的 attachment ID 传给CONFLUENCE_DOWNLOAD_ATTACHMENT即可下载该文件内容。1. CONFLUENCE_GET_ATTACHMENTS(page_id...) → 附件列表提取 attachment_id 2. CONFLUENCE_DOWNLOAD_ATTACHMENT(attachment_id..., connected_account账户ID) → 文件内容这种先列后下的设计让 Agent 可以先让用户确认要哪个附件再执行真正的下载避免盲目拉取大文件。注意两步都需要在正确的 connected account 上下文中执行参见第 2 节因为附件的可见范围与用户的 Confluence 权限绑定。小结Confluence 集成的完整检查清单将以上要点汇总为一份可操作的清单供接入与排障时对照环节关键动作常见错误Scope 配置按端点 v1/v2 对齐 classic/granular scopes塞入无关 space scopeOAuth 成功但工具执行报错刷新令牌配置offline_access并新建 connected account只改 auth config 不重连刷新能力不生效Redirect URI复制当前 auth-config 回调与 Atlassian 应用一致复用 legacy v1/v3 回调路径工具执行传 connected account ID核对 SDK 版本对应的 UUID/nano ID 格式误传 auth config ID / integration ID页面更新CONFLUENCE_GET_PAGE_VERSIONS与CONFLUENCE_UPDATE_PAGE配对用过期版本号更新被拒附件下载CONFLUENCE_GET_ATTACHMENTS取 ID 后交给CONFLUENCE_DOWNLOAD_ATTACHMENT跳过列附件步骤无 ID 可传MCP 场景从listTools的annotations读取 scope 做比对忽略注解scope 错配难排查本文全部结论均可在仓库中溯源核心支持知识见 docs/kb/articles/toolkits-confluence.md 及其源文档 docs/kb/source/toolkits/confluence/public.md自定义 OAuth 的整体配置方式见 docs/content/docs/auth-configuration/custom-auth-configs.mdxconnected account 与 auth config 的职责划分及按连接执行工具的通用语义见 docs/content/docs/auth-configuration/connected-accounts.mdx。按上述清单逐项核对即可在 Composio 上稳定、安全地让 Agent 读写 Confluence 内容。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考