コマンドラインから Confluence API を扱う

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

Confluence API を CLI 中心で使う

コマンドラインから Confluence API を扱う方法は 2 つあります。curl で Confluence Cloud の REST API に生の HTTP リクエストを組み立てるか、それらのエンドポイントを名前付きコマンドでラップした CLI を使うかです。この記事では後者を扱います。ここで紹介する例はすべて 1 つのコマンドで、直接呼び出すときとまったく同じ、公開された Confluence REST API と通信します。違うのは、トークン、ヘッダー、ページネーションのカーソル、JSON の解析といった定型作業が不要な点です。

使うのは atlassian-cli です。Jira、Confluence、Bitbucket、Jira Service Management をカバーする単一の Rust バイナリです。Confluence については、日常的に使う API の機能を提供します。ページの一覧表示と編集、スペースの管理、そして Confluence Query Language（CQL）による検索です。REST のエンドポイントやペイロードを低レベルで解説したものが必要な場合は、対になる Confluence REST API ガイドをご覧ください。この記事は CLI 中心で進めます。

一度だけ認証する

Confluence API は Atlassian アカウントのメールアドレスと API トークンを使います。一度認証して認証情報を名前付きのプロファイルに保存すれば、以降のコマンドはそれを再利用します。リクエストごとにヘッダーを組み立てる必要はありません。

# Log in once and mark this profile as default
atlassian-cli auth login \
  --profile work \
  --base-url https://your-domain.atlassian.net \
  --email you@example.com \
  --token $ATLASSIAN_API_TOKEN \
  --default

# Confirm the token works against the API
atlassian-cli auth test --profile work

トークンは Atlassian アカウントのセキュリティ設定から生成し、シェルの履歴に残らないよう環境変数として export してください。以降、confluence コマンドは --profile で別のインスタンスを指定しない限り、既定のプロファイルを対象にします。詳細は認証ガイドをご覧ください。

複数の Confluence サイトを扱うための仕組みがプロファイルです。サンドボックスや顧客テナント用に 2 つ目の --profile 名でログインしておけば、同じコマンドを別の --profile フラグで実行し直すだけで、一方の変更をもう一方へ反映できます。変わるのは使う認証情報だけなので、まず使い捨てのスペースでスクリプトを試すのが安全です。

ページを操作する

ページは Confluence API の中心となるオブジェクトです。confluence page グループはライフサイクル全体をカバーします。一覧表示、読み取り、作成、更新、削除に加えて、バージョン、ラベル、コメント、閲覧制限も扱えます。

# List pages in a space
atlassian-cli confluence page list --space DEV --limit 25

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

# Create a page (body is Confluence storage-format HTML)
atlassian-cli confluence page create \
  --space DEV \
  --title "Release Notes 1.0" \
  --body "<p>Shipped today.</p>"

# Update an existing page's title
atlassian-cli confluence page update 12345 --title "Release Notes 1.0 (final)"

--body の値は Confluence のストレージ形式、つまり XHTML です。したがってテンプレート化できます。自前のパイプラインで Markdown や HTML をレンダリングし、その結果をそのまま渡せます。単発の編集ではなく、繰り返し使える Markdown から Confluence への流れが目的なら、Confluence を Markdown にエクスポートすると Markdown 同期ランブックをご覧ください。

実務上の注意がひとつあります。ページ関連のコマンドの多くは、タイトルではなく数値のページ ID を鍵にします。タイトルしか分からない場合は、まず CQL で簡単に検索し、出力から ID を取得して page get や page update に渡してください。この 2 段階のパターン（検索で ID を解決し、その ID に対して操作する）は、これから書くほぼすべての Confluence 自動化の土台になります。タイトルは変わりますが、ID は安定しているからです。

作成と編集のほかに、同じグループでは通常なら Web UI を開かざるを得ないメタデータも扱えます。

# See the full version history of a page
atlassian-cli confluence page versions 12345

# Tag pages so they are easy to find later with CQL
atlassian-cli confluence page add-label 12345 reviewed

# Read and add comments without leaving the terminal
atlassian-cli confluence page comments 12345
atlassian-cli confluence page add-comment 12345 "Approved for publishing."

# Inspect who can edit a page
atlassian-cli confluence page get-restrictions 12345

スペースを操作する

スペースはページを収める入れ物です。confluence space グループでは、スペースの列挙、確認、作成ができます。新しいチーム向けのドキュメントを立ち上げるときや、既存のスペースを棚卸しするときに便利です。

# List spaces you can see
atlassian-cli confluence space list --limit 10

# Inspect one space by key
atlassian-cli confluence space get DEV

# Provision a new space in one command
atlassian-cli confluence space create \
  --key DOCS \
  --name "Documentation" \
  --description "Team docs"

# Review who has access
atlassian-cli confluence space permissions DEV

スペースキーは安定しているため、これらのコマンドはそのままスクリプトに組み込めます。新しいチームのオンボーディング用スクリプトなら、スペースの作成、page create によるランディングページの用意、読み取り権限の付与までを 1 つのファイルで行えます。すぐ使えるレポートの例はスペースレポートランブックをご覧ください。

CQL で検索する

Confluence Query Language は API の中で最も強力な機能ですが、生の HTTP から使うと最も面倒でもあります。クエリを自分で URL エンコードし、カーソルをたどってページ送りする必要があるからです。CLI では 3 つの入り口が用意されています。

# Full CQL: the most expressive option
atlassian-cli confluence search cql \
  "space = DEV and type = page and title ~ 'runbook'" \
  --limit 10

# Plain full-text search across everything you can read
atlassian-cli confluence search text "meeting notes" --limit 10

# Scope a text search to a single space
atlassian-cli confluence search in-space DEV "api docs"

CQL は space、type、title、label、creator、lastmodified といったフィールドに対応し、AND や OR、部分一致の ~ のような演算子と組み合わせられます。よく使うクエリをいくつか挙げます。

# Everything with a given label
atlassian-cli confluence search cql "label = deprecated"

# Stale pages: not touched in over a year
atlassian-cli confluence search cql "type = page and lastmodified < now('-365d')"

# Pages a specific person created in one space
atlassian-cli confluence search cql "space = DEV and creator = 'you@example.com'"

古いページを探す CQL クエリを一括クリーンアップランブックと組み合わせれば、Web UI を一切使わずに棚卸しからアーカイブまでを繰り返し実行できるワークフローになります。

API の出力をスクリプトに渡す

どのコマンドも既定では人が読みやすい表を出力しますが、Confluence API をスクリプト化する目的は構造化データを取り出すことです。任意のコマンドに --format json（または csv、yaml、markdown）を追加して、必要な場所へパイプしてください。

# Pull page keys out of a CQL search with jq
atlassian-cli confluence search cql "space = DEV and type = page" \
  --format json | jq '.[].title'

# Wrap list output in {"data":[...],"count":N} for easy parsing
atlassian-cli confluence page list --space DEV --format json --envelope

# Snapshot an entire space to a JSON file for backup or diffing
atlassian-cli confluence bulk export \
  --cql "space = DEV" \
  --output backup.json \
  --format json

--envelope フラグは特筆に値します。一覧のレスポンスを count を含むオブジェクトで包むため、配列が返るのか単一のオブジェクトが返るのかを推測せずに済み、後続の解析が予測しやすくなります。bulk export、bulk add-labels、bulk delete といった一括コマンドは --dry-run も受け付けるので、変更前に影響範囲を確認できます。バックアップの手順一式はConfluence バックアップランブックをご覧ください。

CLI コマンドと素の REST 呼び出しの比較

CLI は Confluence REST API の代替ではなく、その前面に立つインターフェースです。以下の表では、よくある作業を素のやり方とコマンドで対比しています。どちらができることが多いかという話ではなく、コマンドを使うとエンコード、ヘッダー、ページネーションといった定型処理がなくなる点に価値があります。

CLI がすることはすべて、curl と十分なスクリプトがあれば再現できます。要点は、その必要がほとんどないことです。実務の 80% をカバーする Confluence API のよく使う 20% は、覚えられる数のコマンドとしてすでにラップされています。すべての一覧はコマンドリファレンスにあります。

よくある質問

関連リソース