Help us understand the problem. What is going on with this article?

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 になっているページ数」なども取得できるでしょう。

ymkjp
人間がコンピューターの仕事を奪うな (˘ω˘ )
https://ymkjp.wordpress.com/
atlassian
Team Up. 次の何かを生み出すために。新しい価値あるモノを創るための、シンプルで徹底的に柔軟性の高いコラボレーションソフトウェアを提供します。
https://ja.atlassian.com
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした