Confluence APIを使ってConfluence上に新規ページを作成する

はじめに

Confluenceとは

ja.atlassian.com

Atlassian社製のチームコラボレーション・ナレッジマネージメントサービス。平たく言うと社内Wiki的なやつですね。

Qiita:Team、esa.io、Kibela、Crowi、Notionあたりと競合する領域ですかね。

以下、コンフルと呼びます。

やりたいこと

社内Wikiなので、こう言うのは基本的に多くの情報を溜め込むことが大事だと思うわけですが、定型的なフォーマットのページ作成とかは極力自動化して、勝手に情報を溜め込んでおいて欲しいですよね。

というわけでページ自動生成の手始めとして、まずはAPIを使ってコンフル上にページを作成する方法を調べたのでそのメモです。

API説明

基本的には公式ドキュメント通りです。詳細知りたい方はこちらへ。

https://developer.atlassian.com/cloud/confluence/rest/

APIトークン取得

まずはAPI叩くために必要なAPIトークンを取得します。

こちらのAtlassian IDの管理ページから。

id.atlassian.com

「セキュリティ」タブの中のこの辺。

その中のこの辺ですね。

ここで作成されたAPIトークンをメモっておきます。1度閉じるとそのトークンは再表示できない（作り直しになる）ので注意。

コンテンツ取得API

ページ作成の前に、とりあえず現状存在するページを取得して、どんな構造かざっと見ておきましょう。

（長いのでレスポンス貼り付け省略）

コンテンツ一覧取得API

curl -X GET 'https://{your_atlassian_domain}/wiki/rest/api/content' \
  -u '{your_email_address}:{your_api_token}' \
  -H 'Accept: application/json'

コンテンツID指定取得API

curl -X GET 'https://{your_atlassian_domain}/wiki/rest/api/content/{content_id}' \
  -u '{your_email_address}:{your_api_token}' \
  -H 'Accept: application/json'

拡張表示

↑のコンテンツID指定取得APIを叩いてみると、基本的なページの属性情報は出てくるんですが、肝心のページ本文っぽいところは見当たりません。

どうやらデフォルトでは全部の属性は表示しない仕様らしく、必要に応じて以下のパラメータをつけて詳細表示することができます。

~/wiki/rest/api/content/{content_id}?expand={options,options,...}

例えばページに保存されている本文を出したい場合はこんな感じになります。

~/wiki/rest/api/content/{content_id}?expand=body.storage

ここに指定するオプションは結構いっぱいあって、詳しくは公式ドキュメント参照のこと。

コンテンツ作成API

では本題のページ作成です。

curl -X POST 'https://{your_atlassian_domain}/wiki/rest/api/content' \
  -u '{your_email_address}:{your_api_token}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "API POST TEST",
  "type": "page",
  "space": {
    "key": "{your_key_of_space}"
  },
  "status": "current",
  "ancestors": [
    {
      "id": "{ancestors_content_id}"
    }
  ],
  "body": {
    "storage": {
      "value": "<h3>test</h3><br/>test post from api",
      "representation": "storage"
    }
  }
}'

• title : ページのタイトル
• type : ページの種類（ page, blogpost, comment, attachment ）
• space : コンフルのどのスペースかを指定
• status : ページの状態（デフォルトは公開状態 current 、その他状態としては trashed, historical, draft）
• ancestors : そのページの親となるコンテンツIDを指定
• body : ページ本文

指定内容に問題なければ、これでページが作られるはずです。

コンテンツ更新API

参考までに、一度投稿した内容を更新したい場合はこんな感じになります。

基本的な設定項目はあまり変わらず、PathにコンテンツIDを指定してPUTする形です。

curl -X PUT 'https://{your_atlassian_domain}/wiki/rest/api/content/{content_id}' \
  -u '{your_email_address}:{your_api_token}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "version": {
    "number": {integer_version_number}
  },
  "title": "API PUT TEST",
  "type": "page",
  "status": "current",
  "ancestors": [
    {
      "id": "{ancestors_content_id}"
    }
  ],
  "body": {
    "storage": {
      "value": "<h3>test</h3><br/>test put from api",
      "representation": "storage"
    }
  }
}'

1点、新たに version を指定する必要があります。ページの更新履歴管理のためのバージョン番号ですね。

おわりに

こんな感じで定型的なページは自動作成できるかと思うので、自分はこれをBitriseのスクリプトに仕込んで、アプリのベータ版を社内配布するタイミングでそのリリースノートをコンフルへ自動追記する、みたいな使い方をしてます。ぜひ色々お試しくださいませ。

あ、全然関係ないですが、ぺちコン仙台のLT枠登壇決まりました。PHP全く関係ない話をします。