Confluence REST API 不支持直接上传 XML 创建页面，需先解析 XML 提取 title 和 body.storage.value，再以 JSON 格式调用 POST /rest/api/content；宏、附件、子页面需单独处理。
Confluence REST API 不支持直接上传 XML 创建页面
Confluence 的官方 REST API 没有提供「上传任意 XML 文件并自动解析为页面」的端点。所谓“XML 页面导出格式”（如通过 /exportpage.action 生成的 XHTML-like XML）是 Confluence 内部导出/导入机制使用的私有格式，不能直接 POST 给 REST API。试图用 POST /rest/api/content 提交这种 XML 会触发 400 或 500 错误，常见报错如："Invalid value for body: expected map, got string" 或 "Unrecognized field 'version'"（因 XML 结构与 JSON Schema 完全不匹配）。
正确做法：解析 XML 内容，提取 title + body，再调用标准创建接口
如果你手头有一个 Confluence 导出的 .xml 文件（例如从旧空间导出的单页 XML），需先人工或脚本解析它，从中提取两个关键字段：title 和 body.view.value（即 XHTML 格式的正文内容）。然后按标准 JSON 格式构造请求体。
- Confluence 导出 XML 中的页面标题通常在
<title>My Page</title>或<property key="title">My Page</property>节点下 - 正文内容一般包裹在
<content><body><h1>...</h1></body></content>或类似结构中，注意剔除<ac:*>宏标签（它们在 REST API 中不被识别，需转成等效 HTML 或移除） - 必须将提取出的 XHTML 片段包裹进标准的
body.storage.value字段，并声明body.storage.representation = "storage" - 认证必须使用有效 API Token（Basic Auth 或 Bearer Token），且用户需有目标空间的编辑权限
curl -X POST \
'https://your-domain.atlassian.net/wiki/rest/api/content' \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"type": "page",
"title": "My Imported Page",
"space": {
"key": "DEVS"
},
"body": {
"storage": {
"value": "<p>This is <em>imported</em> content.</p>",
"representation": "storage"
}
},
"ancestors": [
{
"id": 123456789
}
]
}'
注意宏（macro）、附件、子页面无法通过 XML 解析自动还原
Confluence 导出 XML 中的 <ac:structured-macro ac:name="toc">、<ri:attachment ri:filename="report.pdf"> 等节点，在 REST API 创建页面时不会被识别或处理。这些元素必须手动转换：
-
<ac:structured-macro>需替换为对应 HTML（如 toc 宏 →<ac:structured-macro ac:name="toc">本身不可用，只能删掉或改用<h2>手动目录） - 附件需单独调用
POST /rest/api/content/{id}/child/attachment接口上传，且必须在页面创建成功后获取其id才能关联 - 子页面关系（
<child-page>）不会被自动创建；需递归解析 XML 树，按父子顺序依次创建页面，并在每页的ancestors中填入上层页面 ID - 导出 XML 中的时间戳、作者信息（
<creator>）在 REST API 创建时会被忽略，实际创建人始终是 API 调用者
推荐替代方案：用 Confluence CLI 或 Python + xml.etree.ElementTree 处理
纯手工提取 XML 内容效率低且易错。更可靠的方式是写轻量脚本解析 XML 并生成标准 JSON 请求体。Python 是常用选择，核心逻辑是：
- 用
xml.etree.ElementTree加载 XML，定位title和body节点 - 对
body内容做最小清洗：移除所有ac:和ri:命名空间前缀的标签（保留内部文本或合理 HTML 替换） - 确保输出的 XHTML 片段是良构的（闭合标签、无嵌套错误），否则 Confluence 存储解析会失败
- 用
requests.post()发送 JSON，检查响应中的id和status字段确认成功
复杂页面含大量宏或自定义样式时，解析成本高，此时应优先考虑 Confluence 自带的「空间导入」功能（.zip 导出包），而非强行走 REST API。
