使用Python与Confluence API更新页面异常：生成新页面而非追加内容

我前阵子用Python操作Confluence API时，正好踩过一模一样的坑！你遇到的核心问题大概率是调用了创建页面的接口而非更新接口，或者更新时没正确传入页面的版本号——Confluence的API对更新操作有严格的版本校验要求，没满足的话就会默认生成新页面归档旧内容。

为什么会生成新页面？ #

Confluence的更新机制依赖「乐观锁」：你必须提供当前页面的version字段值，并且传入的版本号要比现有版本大1，API才会认定这是对原页面的更新操作。如果你的代码里调用的是create_page类接口，或者调用更新接口时没传正确的版本号，系统就会把这次请求当成创建新页面的请求，自动归档旧页面。

正确的追加内容步骤 #

你完全不用复制旧内容重建页面，用官方的更新接口就能直接在原页面末尾追加内容，步骤如下：

• 获取目标页面的现有内容和版本号：调用API拿到页面的当前内容（HTML格式）和版本信息；
• 拼接新内容：把要追加的内容（注意要符合Confluence的HTML格式）拼接到现有内容后面；
• 调用更新接口：传入页面ID、更新后的内容、新的版本号（旧版本号+1），完成原页面的更新。

代码示例（用atlassian-python-api库） #

这是我当时写的可用代码，你可以参考：

from atlassian import Confluence

# 初始化Confluence客户端
confluence = Confluence(
    url='https://你的Confluence实例地址',
    username='你的用户名',
    password='你的API令牌'
)

# 替换成你要更新的页面ID
target_page_id = '123456'

# 获取页面现有内容和版本
page_data = confluence.get_page_by_id(target_page_id, expand='body.storage,version')
existing_html_content = page_data['body']['storage']['value']
current_version = page_data['version']['number']

# 准备要追加的新内容（用Confluence支持的HTML格式）
new_content = """
<hr>
<h3>新增日志：2024-05-20</h3>
<ul>
  <li>完成API追加内容测试</li>
  <li>修复页面更新生成新页面的问题</li>
</ul>
"""

# 拼接新旧内容
updated_content = existing_html_content + new_content

# 执行页面更新
confluence.update_page(
    page_id=target_page_id,
    title=page_data['title'],  # 保持原标题不变
    body=updated_content,
    version={'number': current_version + 1}  # 版本号必须+1
)

对你临时方案的补充 #

你提到的「复制旧内容+追加新内容再重建页面」其实是可行的，但会产生多余的页面版本记录，而且操作比直接调用更新接口繁琐得多，用上面的方法就能完美解决问题啦。

内容的提问来源于stack exchange，提问作者Dan G