ConfluenceのAPI連携入門！Pythonを使って自動でページ作成・更新を効率化する方法
こんにちは！チームの開発プロセスをハックし、ベロシティを極限まで高めるお手伝いをしている先輩エンジニアです。
突然ですが、皆さんのチームでは「ドキュメントの更新」が形骸化していませんか？
「週次の稼働レポートを毎週手動でコピペしてConfluenceに貼り付けている」
「リリースノートを毎回手動で作っていて、たまに更新を忘れる」
こうした「人間がやらなくてもいい単純作業」は、開発チームの貴重な集中力を奪い、ナレッジのサイロ化（情報の属人化・孤立化）を引き起こす最大の原因になります。
そこで今回は、Atlassianが提供する最強のコラボレーションツール「Confluence（コンフルエンス）」のREST APIを使い、Pythonでドキュメントの作成・更新を完全に自動化する第一歩を優しく、かつ実践的に解説します。
この記事を読み終える頃には、退屈なコピペ作業から解放され、チームのナレッジ共有を劇的に加速させる自動化の土台が手に入りますよ。さあ、一緒に自動化の扉を開けましょう！
—
1. なぜ「Python × Confluence API」なのか？
自動化ツールは世の中にたくさんありますが、なぜPythonとConfluence APIの組み合わせが最強なのでしょうか？
1. 圧倒的な「生きた情報」の流通
ソースコード、CI/CDパイプライン、監視ツール（DatadogやPrometheusなど）のデータをPythonで整形し、直接Confluenceに送り込むことで、ドキュメントが「常に最新のダッシュボード」に生まれ変わります。
2. 高い可読性と豊富なライブラリ
Pythonはスクリプトの読みやすさが抜群です。チームの誰もがコードをメンテナンスしやすく、`requests` や `pandas` といった強力なライブラリと組み合わせることで、データの加工から投稿までが数行で完結します。
今回は、特定の複雑なフレームワークに依存せず、HTTPリクエストの基本である `requests` ライブラリを使って、APIの仕組みそのものを理解しながら進めます。基礎を理解しておけば、将来どんなツールや言語にも応用がききますからね。
—
2. 【準備】APIトークンの発行と情報の整理
まずはConfluence APIにアクセスするための「鍵」を手に入れましょう。
セキュリティの観点から、パスワードを直接プログラムに書き込むのはNGです。Atlassianでは「APIトークン」という専用の鍵を発行して認証を行います。
ステップ1: APIトークンの発行
1. [Atlassian APIトークン管理画面](https://id.atlassian.com/manage-profile/security/api-tokens)にアクセスします（ログインを求められたら、普段Confluenceを使っているアカウントでログインしてください）。
2. 「APIトークンを作成する」ボタンをクリックします。
3. 分かりやすいラベル名（例: `python-confluence-bot`）を入力し、作成します。
4. 生成されたトークンを必ずコピーして、安全な場所にメモしてください。（※一度画面を閉じると二度と表示されません！）
ステップ2: 必要な情報の確認
スクリプトを実行するために、以下の4つの情報が必要になります。手元にメモしておきましょう。
1. ConfluenceのURL（ドメイン）
- 例: `https://your-domain.atlassian.net`
2. あなたのメールアドレス
- 例: `developer@example.com`
3. APIトークン
- 先ほど生成した `ATATT…` で始まる文字列です。
4. 投稿先のスペースキー（Space Key）
- Confluenceの対象スペースを開いたとき、URLに含まれる文字列です（例: `https://your-domain.atlassian.net/wiki/spaces/~MYSPACE/…` の場合、`~MYSPACE` または `DS` などの短い英数字）。
—
3. Python環境のセットアップ
それでは、開発環境を作っていきましょう。
安全でクリーンな開発のために、プロジェクトごとに仮想環境（venv）を作成するのがプロの鉄則です。
ターミナル（またはコマンドプロンプト）を開き、以下のコマンドを順番に実行してください。
プロジェクト用のディレクトリを作成して移動
mkdir confluence-automation
cd confluence-automation
Pythonの仮想環境を作成して有効化
python -m venv .venv
macOS / Linuxの場合
source .venv/bin/activate
Windowsの場合 (PowerShell)
.venv\Scripts\Activate.ps1
必要なライブラリのインストール
pip install requests python-dotenv
ライブラリの解説
- `requests`: HTTPリクエストを直感的に送信するための超定番ライブラリです。
- `python-dotenv`: APIトークンなどの機密情報を、ソースコードに直接書かずに `.env` という外部ファイルから安全に読み込むためのライブラリです。
—
4. 環境設定ファイルの作成
セキュリティのベストプラクティスに従い、認証情報を管理する環境変数ファイル `.env` をプロジェクトのルートディレクトリに作成します。
`.env`
CONFLUENCE_URL=https://your-domain.atlassian.net
CONFLUENCE_EMAIL=your-email@example.com
CONFLUENCE_API_TOKEN=your_api_token_here
CONFLUENCE_SPACE_KEY=DEMO
※ `your-domain` や `your-email` などの部分は、先ほどメモしたあなた自身の情報に書き換えてください。
※ この `.env` ファイルは絶対にGitHubなどのパブリックリポジトリにコミット（公開）しないでください。 `.gitignore` に登録しておくことを強くお勧めします。
—
5. 【Hello World】自動で新規ページを作成する
準備は整いました！
まずは、Confluenceに新しいページを自動で1枚作成する「Hello World」スクリプトを書いてみましょう。
Confluenceの本文は、XHTML（Storage Format）と呼ばれる形式で記述します。基本的には通常のHTMLタグ（`
` や `
`）がそのまま使えるので、Web制作の知識があれば非常に直感的にデザインできます。
`create_page.py`
import os
import requests
from requests.auth import HTTPBasicAuth
from dotenv import load_dotenv
.envファイルから環境変数を読み込む
load_dotenv()
環境変数の取得
URL = os.getenv(“CONFLUENCE_URL”)
EMAIL = os.getenv(“CONFLUENCE_EMAIL”)
TOKEN = os.getenv(“CONFLUENCE_API_TOKEN”)
SPACE_KEY = os.getenv(“CONFLUENCE_SPACE_KEY”)
def create_confluence_page():
# APIのエンドポイントを設定 (Confluence Cloud v1 API)
api_url = f”{URL}/wiki/rest/api/content”
# 認証情報の設定 (Basic認証)
auth = HTTPBasicAuth(EMAIL, TOKEN)
# リクエストヘッダーの設定
headers = {
“Accept”: “application/json”,
“Content-Type”: “application/json”
}
# 作成するページのタイトルと本文（HTML形式）
page_title = “🚀 Pythonから自動生成されたページ”
page_body = “””
Hello, Confluence API!
このページはPythonスクリプトから自動的に作成されました。
毎日手動で行っていたレポート作成を、これで自動化できますね！
- 自動化の第一歩クリア！
- ドキュメントの更新漏れゼロへ
“””
# 送信するデータ（ペイロード）の組み立て
payload = {
“type”: “page”,
“title”: page_title,
“space”: {
“key”: SPACE_KEY
},
“body”: {
“storage”: {
“value”: page_body,
“representation”: “storage” # XHTML形式を指定
}
}
}
print(“Confluenceにページを作成中…”)
# POSTリクエストの送信
response = requests.post(
api_url,
json=payload,
auth=auth,
headers=headers
)
# ステータスコードが200(成功)の場合
if response.status_code == 200:
response_data = response.json()
page_link = response_data[“_links”][“base”] + response_data[“_links”][“webui”]
print(“🎉 ページの作成に成功しました！”)
print(f”ページURL: {page_link}”)
else:
print(f”❌ エラーが発生しました。ステータスコード: {response.status_code}”)
print(response.text)
if __name__ == “__main__”:
create_confluence_page()
実行してみましょう！
ターミナルで以下のコマンドを実行します。
python create_page.py
成功した場合の出力：
Confluenceにページを作成中…
🎉 ページの作成に成功しました！
ページURL: https://your-domain.atlassian.net/wiki/spaces/DEMO/pages/123456789/Python
出力されたURLにブラウザでアクセスしてみてください。あなたのPythonコードから送られた綺麗なHTMLページが、瞬時にConfluence上に誕生しているはずです！
—
6. 【現場の知恵】既存のページを「更新」する方法
新規作成ができたら、次は「ページの更新」に挑戦しましょう。実は、ここが多くの初心者が最初につまずくポイントです。
Confluence APIで既存のページを更新（上書き）する場合、「現在のページバージョン」を取得し、それに `+1` したバージョンを指定してリクエストを送る必要があります。これを怠ると、「競合エラー（409 Conflict）」が発生して更新に失敗します。
安全にページを更新するためのフローは以下の通りです。
1. 更新したいページの情報を「タイトル」で検索して、ページIDと現在のバージョンを取得する。
2. 新しい本文を作成し、バージョンを+1して `PUT` リクエストを送信する。
さっそく、この一連の流れを実装したスマートなスクリプトを見てみましょう。
`update_page.py`
import os
import requests
from requests.auth import HTTPBasicAuth
from dotenv import load_dotenv
load_dotenv()
URL = os.getenv(“CONFLUENCE_URL”)
EMAIL = os.getenv(“CONFLUENCE_EMAIL”)
TOKEN = os.getenv(“CONFLUENCE_API_TOKEN”)
SPACE_KEY = os.getenv(“CONFLUENCE_SPACE_KEY”)
auth = HTTPBasicAuth(EMAIL, TOKEN)
headers = {
“Accept”: “application/json”,
“Content-Type”: “application/json”
}
def get_page_info(title):
“””タイトルからページのIDと現在のバージョンを取得する”””
search_url = f”{URL}/wiki/rest/api/content”
params = {
“title”: title,
“spaceKey”: SPACE_KEY,
“expand”: “version”
}
response = requests.get(search_url, params=params, auth=auth, headers=headers)
if response.status_code == 200:
results = response.json().get(“results”)
if results:
page_id = results[0][“id”]
current_version = results[0][“version”][“number”]
return page_id, current_version
return None, None
def update_confluence_page(title, new_html_body):
“””既存のページを新しい内容で安全に更新する”””
# 1. 現在のページ情報を取得
page_id, current_version = get_page_info(title)
if not page_id:
print(f”❌ ページ ‘{title}’ が見つかりませんでした。先に作成してください。”)
return
# 2. 更新用エンドポイントの構築
update_url = f”{URL}/wiki/rest/api/content/{page_id}”
# 3. 新しいバージョンを設定 (現在 + 1)
next_version = current_version + 1
payload = {
“id”: page_id,
“type”: “page”,
“title”: title,
“space”: {“key”: SPACE_KEY},
“body”: {
“storage”: {
“value”: new_html_body,
“representation”: “storage”
}
},
“version”: {
“number”: next_version
}
}
print(f”ページを更新中… (バージョン: {current_version} -> {next_version})”)
# PUTリクエストで上書き更新
response = requests.put(update_url, json=payload, auth=auth, headers=headers)
if response.status_code == 200:
print(“✨ ページの更新に成功しました！”)
else:
print(f”❌ 更新エラー: {response.status_code}”)
print(response.text)
if __name__ == “__main__”:
# 更新対象のページタイトル（先ほど作成したもの）
target_title = “🚀 Pythonから自動生成されたページ”
# 新しい本文（動的なデータやタイムスタンプを模した内容）
from datetime import datetime
current_time = datetime.now().strftime(“%Y-%m-%d %H:%M:%S”)
updated_body = f”””
Hello, Confluence API! (更新版)
このページはPythonスクリプトから自動的に更新されました。
最終更新日時: {current_time}
このように日報や週報、ビルド結果などをスクリプトから定期実行（Cronなど）で書き込むことで、ドキュメントは常に最新に保たれます！
“””
update_confluence_page(target_title, updated_body)
実行と結果の確認
python update_page.py
Confluenceのページをブラウザでリロードしてみてください。ページの右上に「バージョン 2」と表示され、記述した「最終更新日時」が美しく反映されているはずです。
—
7. アジャイルコーチが教える「失敗しないドキュメント自動化」の極意
最後に、これから自動化を進めるあなたへ、現場で大混乱を引き起こさないための3つの設計思想を共有します。
1. 「自動生成されたゴミ」を作らない
APIを使えば、毎日大量のページを自動で作ることができます。しかし、中身のないページが検索結果に溢れかえるのはチームにとって災厄です。「毎日新規作成する」のか、「1つの親ページの下に綺麗にツリー状に配置する」のか、あるいは「1つのページを毎日上書き更新する」のか。ライフサイクルを必ず設計しましょう。
2. テンプレート（Storage Format）の有効活用
Pythonのコード内に長いHTMLを書くのはスマートではありません。本文の構造（テンプレート）は外部の `.html` ファイルに切り出し、Python側で `jinja2` などのテンプレートエンジンを使ってデータ（日付や数値）だけを埋め込むように設計すると、コードの可読性が劇的に向上します。
3. エラーハンドリングと通知
APIの認証切れやネットワークエラーで自動更新が止まったとき、誰も気づかないのは危険です。スクリプトに `try-except` を仕込み、エラー時にはSlackやTeams、Discordへ即座に通知する仕組みを組み合わせておくと、運用フェーズで震えるほど役立ちます。
—
まとめ
お疲れ様でした！
手動でのコピペ作業に終止符を打ち、ドキュメント管理をコードで制御するための強力な一歩を踏み出しましたね。
今回学んだ「認証・情報の取得・新規作成・バージョン制御を伴う更新」という流れは、Confluence APIを扱う上での最も重要かつ本質的なコア技術です。これさえマスターしてしまえば、あとはJiraのタスク状況を引っ張ってきて進捗レポートを作ったり、GitHubのリリースノートを自動転記したりと、応用は無限大です。
「面倒くさいな」と感じる作業を見つけたら、それは自動化のチャンス。
ぜひ、あなたの手でチームのベロシティを次のレベルへ引き上げていってください。
何かわからないことがあれば、いつでもコードの設計図を見せにきてくださいね。応援しています！