使用Confluence API创建/更新页面时遇BadRequestException求助

问题背景 #

调用Confluence API创建或更新页面时，部分HTML标签（如<hr>）会触发400错误：

"message":"com.atlassian.confluence.api.service.exceptions.BadRequestException: Content body cannot be converted to new editor format"
而<p>、<h1>-<h6>等标签可正常使用。

1. 支持的标记语言/格式方案 #

• 使用Confluence原生的storage格式：这是API接受的标准格式，和页面直接编辑的底层格式一致。你可以用Confluence Wiki标记（比如用----表示水平线），或者符合storage规范的结构化标签。
• 类Markdown格式处理：API不直接支持Markdown，但你可以先将Markdown转换为Confluence的storage格式再发送请求。比如Markdown的---对应Confluence的水平线结构化标签。

2. 替代禁用标签的方法 #

Atlassian官方未明确列出禁用的HTML标签，但报错是因为新编辑器采用结构化内容模型，部分原生HTML标签无法映射。以<hr>为例，替代方案：

• 使用Wiki标记：----
• 使用storage格式的结构化宏：<ac:structured-macro ac:name="horizontal-rule"/>

示例请求体（更新页面） #

{
  "version": {
    "number": 2
  },
  "body": {
    "storage": {
      "value": "<p>测试内容</p><ac:structured-macro ac:name=\"horizontal-rule\"/>",
      "representation": "storage"
    }
  }
}

额外建议 #

• 不确定标签是否支持时，可先在Confluence编辑器手动添加对应格式，再通过API获取页面的storage内容，直接复用该格式。
• 所有内容需符合Confluence storage格式规范，避免使用无法映射到新编辑器模型的原生HTML标签。

内容的提问来源于stack exchange，提问作者James Stanbridge