confluence
Atlassian

REST API で Confluence Cloud の総ページ数を知る

More than 1 year has passed since last update.


動機

サーバ版のConfluenceであればAdd-onやUser Macroでページ数を知る方法があります1が、クラウド版のConfluenceではページ数を簡単に取得する方法が提供されていません。そのためAtlassian Answersでも For Confluence Cloud, how do I find the total number of pages? などの質問をよく見かけます。

そこで本エントリではConfluence Cloudでページ数などを取得する方法を紹介します。


解決法

Confluence Cloud REST API を用います。

コードで示すのが手っ取り早いので、下掲します2。試しに次の3つのデータを取得してみます。


  • 総ページ数

  • 総ユーザー数

  • スペース数

ここではスペース横断でアクセスするために admin ユーザーを使用してREST APIにリクエストしています。

※パスワードは API tokens を発行して利用することをおすすめします。


confluence_cloud_rest_api/example.sh

# Be sure that a user has a privilege to access all the Confluence spaces

A_USER="admin"
A_PASSWD="__YOUR_PASSWORD_HERE__"
INSTANCE_HOST="__YOUR_SUBDOMAIN_HERE__.atlassian.net"

# Total number of pages
curl -sGLu ${A_USER}:${A_PASSWD} "https://${INSTANCE_HOST}/wiki/rest/api/search" --data-urlencode 'cql=type IN (blogpost, page)' --data-urlencode 'limit=0' | jq '.totalSize'

# Total number of users
curl -sLu ${A_USER}:${A_PASSWD} "https://${INSTANCE_HOST}/wiki/rest/api/group/confluence-users/member?limit=1000" | jq '.size'

# Number of spaces (Assumed to be less than 1000)
curl -sLu ${A_USER}:${A_PASSWD} "https://${INSTANCE_HOST}/wiki/rest/api/space?limit=1000" | jq '.size'


特に rest/api/search はCQL3が利用できるため強力ですね。


制限

REST APIには次のような制限があります。ただし、1つめの制限に関してはある程度ワークアラウンドがあるため後述します。


  • JQL, CQL で統計用途のクエリが使えない


    • SUMなどの集計関数4や、SQLの GROUP BY 相当の機能5がサポートされていない

    • これは本来 JQL, CQL が issue や page のフィルタリングとして機能提供されているため仕方がない側面もあるが、例えば「作業率 (workratio)」などのビルトインのフィールドを用いることである程度、業務要件は満たすこともできる6



  • ブラウザからのリクエストができない


    • CSRF防止のため *.atlassian.net 以外からのXMLHttpRequestが禁止されている7 8

    • XSS防止のため *.atlassian.net でのHTMLの埋め込みが禁止されている9 10



  • REST APIで取得できない情報がある


    • 例えば、ページビュー数 (PV) を取得するエンドポイントはない




それでもやはり GROUP BY で集計したい

前節で制限をあげましたが、それでも「スペースごとのページ数」などは取得したいところです。

そこでワークアラウンドとして、愚直に複数クエリを投げることで GROUP BY での集計を行います。


例: スペースごとのページ数

前節の例よりも煩雑になります(個人的にはshellとしてギリギリ許容範囲の可読性です)。


confluence_cloud_rest_api/count_pages_by_space.sh

A_USER="admin"

A_PASSWD="__YOUR_PASSWORD_HERE__"
INSTANCE_HOST="__YOUR_SUBDOMAIN_HERE__.atlassian.net"
SPACE_LIMIT="1000"

function space_keys {
curl -sGLu ${A_USER}:${A_PASSWD} "https://${INSTANCE_HOST}/wiki/rest/api/space" --data-urlencode "limit=${SPACE_LIMIT}" | jq -r '.results[].key'
}

function page_num_by_space {
for SPACE in $(space_keys); do
NUM_PAGES=$(curl -sGLu ${A_USER}:${A_PASSWD} "https://${INSTANCE_HOST}/wiki/rest/api/search" --data-urlencode "cql=type IN (blogpost, page) AND space='${SPACE}'" --data-urlencode 'limit=0' | jq '.totalSize')
echo "${SPACE}\t${NUM_PAGES}"
done
}

page_num_by_space | sort -rk2


標準出力として下記のように tsv 形式で表示されます。


STDOUT.tsv

DEF     5

BIJP 2
~admin 1

このように複数クエリを組み合わせることで様々な応用が効くようになります。例えば「ユーザーごとに contributor になっているページ数」なども取得できるでしょう。