为了使用 Python 操作 Confluence 并撰写文章，你可以选择不同的库来实现。根据功能复杂度和社区活跃度，主要推荐 **`atlassian-python-api`** 库，它是一个功能全面且维护良好的官方社区库。此外，`Confluence Python API` 也是一个轻量级的开源选择 [ref_1]。下面将详细介绍如何使用这两个库来完成创建或更新文章（页面）的操作。 ### 一、方案对比与选择 在开始之前，我们先对比一下两种主流方案的核心特点，帮助你做出选择： | 特性维度 | **atlassian-python-api** (推荐) | **Confluence Python API** (参考) | | :--- | :--- | :--- | | **项目背景** | Atlassian 官方支持的社区库，功能全面且持续更新 [ref_6]。 | 第三方开源项目，旨在提供简洁的接口 [ref_1]。 | | **功能覆盖** | **非常广泛**，支持页面、空间、附件、权限、用户、评论、模板等几乎所有 Confluence 操作 [ref_6]。 | **基础核心**，主要专注于页面的获取（`retrieve`）和存储（`store`）功能 [ref_1]。 | | **API 兼容性** | 支持 Confluence Server、Data Center 及 Cloud (REST API v2)，现代且标准。 | 支持 Confluence 3.x 至 5.x 的 API，可能对更新版本支持有限 [ref_1]。 | | **学习成本** | 中等，文档和示例丰富，适合中高级自动化需求。 | 较低，接口简单，适合快速实现基础读写。 | | **适用场景** | 企业级自动化、批量操作、复杂内容管理（如插入附件、管理权限）[ref_6]。 | 简单的脚本任务，如定期抓取或更新少量页面内容。 | **结论**：对于“写文章”这一任务，若涉及复杂格式、附件或批量操作，强烈推荐使用 `atlassian-python-api`。若仅需实现最基本的文本内容推送，`Confluence Python API` 亦可作为备选。 ### 二、使用 atlassian-python-api 创建/更新文章 这是目前功能最强大、最推荐的方法。 #### 1. 环境准备 首先，你需要安装该库并进行基础配置。 ```python # 安装 atlassian-python-api 库 # 在终端或命令行中执行：pip install atlassian-python-api from atlassian import Confluence # 配置 Confluence 连接信息 [ref_6] confluence = Confluence( url='https://your-confluence-site.atlassian.net', # 你的 Confluence 地址 username='your-email@example.com', # 你的用户名（Cloud版为邮箱） password='your-api-token', # 强烈建议使用 API Token 而非密码 [ref_6] cloud=True # 如果是 Cloud 版本设为 True，Server/DC版设为 False ) # 注意：对于 Server/Data Center 版本，可能使用以下方式认证： # confluence = Confluence(url='http://your-server/confluence', username='admin', password='password', cloud=False) ``` #### 2. 创建新页面（文章） 创建一个新页面需要指定其所属的空间（Space）和父页面（可选）。 ```python # 定义页面内容，使用 Confluence 存储格式 (CFS) 或 wiki 标记，推荐使用 HTML 格式以获得更好控制 [ref_6] page_title = "我的第一篇Python API文章" space_key = "DEMO" # 空间键，例如 ‘TST’, ‘DOC’ 等 content_body = """ <h1>欢迎阅读</h1> <p>这篇文章是通过 <strong>atlassian-python-api</strong> 库自动创建的。</p> <ul> <li>支持丰富的文本格式。</li> <li>可以插入图片和附件。</li> <li>便于实现知识库的自动化更新。</li> </ul> <p>创建时间：2023-10-27</p> """ # 创建页面，如果不指定 parent_id，则创建为空间的首页 [ref_6] try: status = confluence.create_page( space=space_key, title=page_title, body=content_body, parent_id=None, # 如果需要嵌套在某个页面下，在此处填写父页面的ID type='page', # 页面类型，也可以是 'blogpost' representation='storage' # 内容格式，'storage' 对应 Confluence 存储格式 ) if status: print(f"页面创建成功！页面ID: {status['id']}, 链接: {confluence.url}/spaces/{space_key}/pages/{status['id']}") else: print("页面创建失败。") except Exception as e: print(f"创建页面时发生错误: {e}") ``` #### 3. 更新现有页面 如果你需要更新一个已存在的页面，需要先获取该页面的ID，然后进行更新。 ```python # 首先，根据标题和空间查找页面ID [ref_6] page_title_to_update = "我的第一篇Python API文章" existing_page = confluence.get_page_by_title(space=space_key, title=page_title_to_update) if existing_page: page_id = existing_page['id'] new_content = """ <h1>已更新的文章</h1> <p>此页面内容已被 <code>Python脚本</code> 自动更新。</p> <p>新增了一段说明文字，并修正了之前的排版。</p> """ # 更新页面内容，同时可以增加版本注释 [ref_6] update_status = confluence.update_page( page_id=page_id, title=page_title_to_update, # 标题也可以同时更新 body=new_content, version_comment='通过Python API自动更新内容' ) if update_status: print(f"页面更新成功！新版本号: {update_status['version']['number']}") else: print("页面更新失败。") else: print(f"未在空间 '{space_key}' 中找到标题为 '{page_title_to_update}' 的页面。") ``` #### 4. 高级功能示例：附加图片与使用模板 `atlassian-python-api` 支持更复杂的操作，例如附加文件或使用预定义的页面模板。 ```python # 示例：向页面附加一张图片 page_id = "123456" # 目标页面的ID attachment_path = "./screenshot.png" try: with open(attachment_path, 'rb') as file: confluence.attach_file(file, page_id=page_id, comment='上传的图表截图') print("附件上传成功。") except FileNotFoundError: print("指定的文件不存在。") except Exception as e: print(f"上传附件时发生错误: {e}") # 示例：使用模板创建页面 (如果Confluence实例配置了模板) [ref_6] # template_content = confluence.get_template_by_name(space_key, “报告模板”) # 然后可以将 template_content 作为 body 的一部分进行创建或更新。 ``` ### 三、使用 Confluence Python API 创建文章 作为备选方案，如果你选择使用更轻量的 `Confluence Python API`，其基本步骤如下。请注意，该库可能对现代 Confluence Cloud 的 REST API 支持不如前者完善。 ```python # 假设你已根据项目文档安装并配置了 Confluence Python API 库 [ref_1] from confluence_api import ConfluenceAPI # 初始化客户端，通常通过配置文件设置URL和认证信息 [ref_1][ref_5] config = { 'url': 'https://your-confluence.atlassian.net', 'username': 'your-email@example.com', 'password': 'your-api-token' } api = ConfluenceAPI(config) # 定义页面数据 page_data = { 'spaceKey': 'DEMO', 'title': '轻量库测试文章', 'content': '这是使用 Confluence Python API 库创建的内容。', 'parentId': None # 可选，父页面ID } # 调用库的存储功能来创建页面 [ref_1] try: result = api.store_page(page_data) print(f"页面创建结果: {result}") except Exception as e: print(f"操作失败，错误信息: {e}") # 该库可能包含了更健壮的异常处理机制 [ref_1] ``` ### 四、最佳实践与常见问题 1. **认证安全**： * 切勿在代码中硬编码密码。对于 Confluence Cloud，务必使用 [API Token](https://id.atlassian.com/manage-profile/security/api-tokens)。对于 Server/DC 版，考虑使用个人访问令牌或从环境变量/安全 vault 读取凭据 [ref_6]。 * 示例：`password = os.environ.get('CONFLUENCE_API_TOKEN')` 2. **错误处理**： * 网络超时、认证失败、权限不足、内容格式错误是常见问题。务必使用 `try-except` 块包裹核心 API 调用，并记录详细的错误日志以便排查 [ref_5]。 3. **内容格式**： * Confluence 主要支持 `storage` (HTML-like)、`wiki` 和 `view` 格式。`atlassian-python-api` 的 `create_page` 和 `update_page` 方法默认或常用 `representation='storage'`。确保你传入的内容是合法格式，否则更新会失败 [ref_6]。 4. **速率限制**： * 频繁调用 API 可能会触发 Confluence 的速率限制。在批量操作中，建议在请求间添加适当的延迟（例如 `time.sleep(0.5)`）[ref_6]。 5. **页面查找**： * 在更新前，最可靠的方式是通过 `confluence.get_page_by_title()` 获取精确的页面ID，因为标题可能存在重复或特殊字符 [ref_6]。 通过以上步骤和示例，你可以根据项目复杂度和团队熟悉度，选择最适合的库来实现 Python 对 Confluence 文章的自动化编写与管理。对于大多数生产环境，从功能、维护性和社区支持角度，`atlassian-python-api` 是更优的选择 [ref_6]。