Confluence REST API 実践ガイド

atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援のいずれも受けておらず、Atlassian が提供する公式 CLI（acli）でもありません。製品名は互換性を示す目的でのみ使用しています。

Confluence REST API とは

Confluence REST API は、Confluence Cloud のコンテンツ、つまりページ、ブログ記事、スペース、添付ファイル、ラベル、コメントを読み書きするための Atlassian の HTTP インターフェースです。Web UI でできることは、トークンと JSON ボディがあれば HTTPS 経由で操作できます。Confluence Cloud の現行バージョンは v2 で、https://your-domain.atlassian.net/wiki/api/v2 配下から提供されます。/wiki というプレフィックスは Confluence 固有なので、省略しないでください。

API を使う目的は、たいていドキュメント作業の自動化です。リポジトリからリリースノートを同期する、生成したレポートを公開する、古いページに一括でラベルを付ける、スペースをバックアップに取り込む、といった用途です。このガイドでは、実際に手を動かすために必要な部分を扱います。v2 のリソースモデル、API トークンによる認証の仕組み、ターミナルに貼り付けてそのまま使える curl の実例、そしてページネーションです。そのうえで、atlassian-cli が同じエンドポイントをどうラップし、リクエストを自分で組み立てる必要をほとんどなくすかを示します。

Confluence REST API v2 の構成

Confluence REST API には現役のバージョンが 2 つあり、どちらを相手にしているかを把握しておくと役立ちます。v2 は新規の連携で推奨される現行のインターフェースです。v1 は古いものの今も利用でき、v2 に移行されていない機能をいくつか担っています。もっとも重要な差は、CQL によるコンテンツ検索が今も v1 にあることです。

実際には、両方を同時に使うチームが多くあります。ページとスペースの読み書きは v2、CQL 検索は v1 という具合です。これは想定された普通の使い方です。避けたいのは、v2 がすでに対応しているリソースなのに、新規の連携を v1 だけで組んでしまうことです。

API トークンによる認証

スクリプトからもっとも簡単な方法は、Atlassian アカウントのメールアドレスと API トークンによる HTTP Basic 認証です。id.atlassian.com の Security > API tokens でトークンを作成し、パスワードとして渡します。エンドユーザー向けのアプリケーションでは代わりに OAuth 2.0 を使いますが、自動化や CI ではトークンが最短の道です。

共有するスクリプトにシークレットを貼り付けずに済むよう、認証情報は環境変数に設定します。

# Store credentials once, per shell session
export CONF_EMAIL="you@example.com"
export CONF_TOKEN="your_api_token"
export CONF_BASE="https://your-domain.atlassian.net/wiki"

# List the first 25 pages you can see
curl -s -u "$CONF_EMAIL:$CONF_TOKEN" \
  "$CONF_BASE/api/v2/pages?limit=25" \
  -H "Accept: application/json"

-u "email:token" フラグを付けると、curl が Basic 認証ヘッダーを組み立ててくれます。呼び出しが 401 を返す場合はトークンかメールアドレスが誤っています。403 の場合は認証情報は正しく、そのリソースへの権限が足りていません。トークンはパスワードと同じように扱ってください。漏えいしたらローテーションし、自動化には専用のサービスアカウントを使うのが安全です。

主要な v2 エンドポイントと実例

Confluence の自動化のほとんどは、スペース、ページ、ページ本文、バージョンの 4 つのリソースを扱います。もっともよく使うリクエストは次のとおりです。

スペースキーから ID を解決する

v2 はスペースをキーではなく数値の ID で参照するため、DEV のような分かりやすいキーから ID を調べるところから始めることがよくあります。

curl -s -u "$CONF_EMAIL:$CONF_TOKEN" \
  "$CONF_BASE/api/v2/spaces?keys=DEV" \
  -H "Accept: application/json"

ページを本文つきで取得する

v2 は既定ではページ本文を返しません。body-format で明示的に指定します。よく使う表現形式は storage（Confluence のストレージ形式 XHTML）と atlas_doc_format（ADF の JSON）です。

curl -s -u "$CONF_EMAIL:$CONF_TOKEN" \
  "$CONF_BASE/api/v2/pages/12345?body-format=storage" \
  -H "Accept: application/json"

ページを作成する

ページの作成は、数値の spaceId、ステータス、タイトル、本文を付けて /pages に POST します。

curl -s -u "$CONF_EMAIL:$CONF_TOKEN" \
  -X POST "$CONF_BASE/api/v2/pages" \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": "65601",
    "status": "current",
    "title": "Release Notes 1.2",
    "body": { "representation": "storage", "value": "<p>Shipped.</p>" }
  }'

ページを更新する

更新はつまずきやすい箇所です。v2 では、現在のバージョンよりちょうど 1 つ大きい新しいバージョン番号を、id、ステータス、タイトルとあわせて送る必要があります。誤ったバージョンを送ると、同時編集の上書きを防ぐために API が書き込みを拒否します。

curl -s -u "$CONF_EMAIL:$CONF_TOKEN" \
  -X PUT "$CONF_BASE/api/v2/pages/12345" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "12345",
    "status": "current",
    "title": "Release Notes 1.2",
    "body": { "representation": "storage", "value": "<p>Updated.</p>" },
    "version": { "number": 2 }
  }'

CQL で検索する（v1）

ID で取得するのではなくクエリでコンテンツを探したい場合は、v1 の検索エンドポイントを使います。CQL（Confluence Query Language）は UI の詳細検索と同じ構文です。

curl -s -u "$CONF_EMAIL:$CONF_TOKEN" \
  "$CONF_BASE/rest/api/content/search?cql=space%3DDEV%20and%20type%3Dpage&limit=25" \
  -H "Accept: application/json"

ページネーションと本文の形式

v2 はカーソルベースのページネーションを使います。一覧のレスポンスには、不透明なカーソルを含む相対 URL を保持する _links.next フィールドが入ります。すべての結果をたどるには、_links.next がなくなるまで追い続けます。

# First page returns something like:
# { "results": [ ... ], "_links": { "next": "/wiki/api/v2/pages?cursor=eyJpZ..." } }

# Follow the cursor for the next page
curl -s -u "$CONF_EMAIL:$CONF_TOKEN" \
  "https://your-domain.atlassian.net/wiki/api/v2/pages?cursor=eyJpZ..." \
  -H "Accept: application/json"

カーソルを自分で組み立てたり、ページ番号だとみなしたりしないでください。不透明な値として扱い、前回のレスポンスから読み取ってそのまま渡します。これは、数値の start と limit のオフセットでページ送りしていた v1 との最大の挙動の違いです。

本文の形式は、コンテンツの作り方に合わせて選びます。Confluence のマークアップを直接書くなら storage、構造化された ADF として組み立てるなら atlas_doc_format を使います。読み取り専用の表示であれば、レンダリング済みの HTML を返す view を指定できます。この解析処理に加えて、カーソルのループやバージョン番号の加算といった作業こそ、ラッパーが取り除いてくれるつなぎのコードです。

curl を書かずに済ませる: ラッパーとしての atlassian-cli

同じ認証ヘッダー、カーソルのループ、JSON パーサーを何度か書けば、ラッパーの魅力は明らかです。atlassian-cli は、これらのエンドポイントに直接対応する単一の Rust バイナリです。認証情報を一度保存し、ページネーションを代わりにたどり、見やすいテーブルや JSON を出力します。

名称について: atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けておらず、Atlassian が提供する公式 CLI（acli）でもありません。ベンダーによる公式サポートが必要であれば acli を使ってください。Jira、Confluence、Bitbucket、Jira Service Management を横断し、どこでも同じフラグ規約で扱える無料の単一バイナリが欲しい場合は atlassian-cli を使ってください。

一度認証すれば、トークンは名前付きのプロファイルに保存されます。

atlassian-cli auth login \
  --profile work \
  --base-url https://your-domain.atlassian.net \
  --email you@example.com \
  --token $CONF_TOKEN \
  --default

あとは、これまで見てきた操作が 1 行で済みます。ベースパスも、_links.next のループも、バージョン番号の計算も不要です。

# List pages in a space (pagination handled for you)
atlassian-cli confluence page list --space DEV --limit 25

# Read a page by ID
atlassian-cli confluence page get 12345

# Create a page
atlassian-cli confluence page create \
  --space DEV \
  --title "Release Notes 1.2" \
  --body "<p>Shipped.</p>"

# CQL search, same query language as the raw v1 endpoint
atlassian-cli confluence search cql "space = DEV and type = page" --limit 25

すべてのコマンドがグローバルな --format フラグを受け付けるため、JSON、CSV、YAML、終了コードだけを返す静かなモードを選べます。これにより、API を curl して jq に流すようなスクリプトを、そのまま CLI で置き換えられます。

# Machine-readable output straight into jq
atlassian-cli confluence page list --space DEV \
  --format json | jq '.[].title'

もっと重い保守作業には一括系のコマンドもあります。atlassian-cli confluence bulk add-labels --cql "space = DEV" --labels docs,reviewed --dry-run は、大量のラベル変更を実行前にプレビューします。confluence bulk export はスペース全体を JSON ファイルに書き出します。コマンドの一覧はコマンドリファレンスをご覧ください。

API を直接呼ぶか CLI を使うか

どちらの方法も、行き着く先は同じ Confluence REST API です。違いは、つなぎのコードをどこまで自分で持つかです。

よくあるやり方は、まず CLI で試作してワークフローを固め、CLI が対応していないものが必要になったときだけ生の HTTP に降りることです。さらに深く知りたい場合は、CLI から Confluence API を使うの解説や Confluence 自動化ガイド、あるいは Confluence CLI リファレンスをご覧ください。

よくある質問

関連リソース