如何通过Confluence REST API插入页面宏或创建带附件宏的页面

• 接口调用规则错误：更新现有页面需使用PUT方法请求/rest/api/content/{目标页面ID}，不能使用POST请求内容根路径；且更新操作必须携带version参数，参数值为当前页面最新版本号+1
• JSON格式非法：storage.value字段内部的双引号未做转义，服务端无法解析请求体直接触发500错误
• 字段结构错误：更新页面的请求中body字段结构不符合要求，正确结构为body.storage.value+body.storage.representation，不能直接在body下写value和representation

1. 创建带附件宏的新页面 #

正确curl请求示例：

curl -s -u user:pasw -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' \
-d '{
    "type":"page",
    "ancestors":[{"id":246324831}], 
    "title":"New Page",
    "space":{"key":"TST"}, 
    "body":{
        "storage":{
            "value":"<ac:structured-macro ac:name=\"attachments\"><ac:parameter ac:name=\"old\">false</ac:parameter><ac:parameter ac:name=\"sortBy\">name</ac:parameter><ac:parameter ac:name=\"upload\">true</ac:parameter></ac:structured-macro>",
            "representation":"storage"
        }
    }
}' \
'https://localhost:8080/rest/api/content/?os_authType=basic'

核心修改点：对value内部的所有双引号添加了转义符\，保证JSON格式合法。

2. 向现有页面插入宏 #

前置操作：先查询当前页面的最新版本号 #

调用以下接口获取页面当前版本和原有内容：

curl -s -u user:pasw -X GET 'https://localhost:8080/rest/api/content/246341155?expand=version,body.storage'

返回结果中version.number为当前版本号，将该值+1作为更新请求的版本参数；如果需要保留页面原有内容，需将宏代码拼接在原有body.storage.value的对应位置后再提交更新。

正确更新请求示例： #

curl -s -u user:pasw -X PUT -H 'Content-Type: application/json' \
-d '{
    "id":"246341155",
    "type":"page",
    "space":{"key":"TST"},
    "version":{
        "number": 2 # 替换为你查询到的当前版本号+1
    },
    "body":{
        "storage":{
            "value":"<p>原有页面内容</p><ac:structured-macro ac:name=\"attachments\"><ac:parameter ac:name=\"old\">false</ac:parameter><ac:parameter ac:name=\"sortBy\">name</ac:parameter><ac:parameter ac:name=\"upload\">true</ac:parameter></ac:structured-macro>",
            "representation":"storage"
        }
    }
}' \
'https://localhost:8080/rest/api/content/246341155'

如果插入的宏包含<、>、&等特殊字符，需提前做HTML实体编码，避免存储格式解析错误。

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