
Backlog APIを使って Wiki 一覧(リンク付き)を取得する Python製 CLIを作ってみる
はじめに
『Backlog Wiki で今まで作ってきたページ一覧をさくっと取得したいな…』 とふと思い作ってみました。
以下のような利用イメージです。
▼ 実行コマンド
python get-backlog-wikis.py ${APIKEY} ${SPACE} ${PROJECT} --syntax md
▼ 取得できるテキスト例
▼ 取得できるテキスト例 (Markdown プレビュー)
事前準備
Python Fire 導入
Python Fire は Python製 CLIを簡単に作ることができるツールです。 今回はこれを使います。
弊社ブログに紹介ブログがあるので詳しくは以下を参照ください。
私は Mac 環境なので 以下コマンドで Python Fire をインストールしました。
pip install fire
Backlog APIキー 取得
APIキーを取得しておきましょう。 Backlog の [個人設定 > API] から取得できます。
スクリプトを書いてみる
以下 Pythonスクリプトを作成しました。
import sys | |
import requests | |
import json | |
import fire | |
def _item_line(text: str, level: int, syntax: str) -> str: | |
"""リストアイテム形式の文字列へ変換する | |
Args: | |
text (str): テキスト | |
level (int): リストのレベル(1以上) | |
syntax (str): シンタックス(Markdown `md` or Backlog `bl` or Org-mode `org`) | |
Returns: | |
str: リストアイテム形式の文字列 | |
""" | |
line = " " * (level - 1) + "- " + text | |
if syntax == "bl": | |
line = "-" * level + " " + text | |
elif syntax == "org": | |
line = " " * (level - 1) + "- " + text | |
return line | |
def _convert_to_text(space: str, wikis: list, syntax: str) -> str: | |
"""wiki一覧をテキスト(リスト形式)へ変換する | |
Args: | |
space (str): Backlog スペースID | |
wikis (list): wiki一覧の情報 | |
syntax (str): シンタックス(Markdown `md` or Backlog `bl` or Org-mode `org`) | |
Returns: | |
str: テキスト(リスト形式) | |
""" | |
# wiki 'name' のインデックスを作成 | |
name_to_id = {} | |
for wiki in wikis: | |
name_to_id[wiki['name']] = wiki['id'] | |
# 取りうる全てのファイル/ディレクトリのパスを取得、ソート | |
all_paths_set = set() | |
for wiki in wikis: | |
elems = wiki['name'].split('/') | |
for i in range(1, len(elems) + 1): | |
all_paths_set.add("/".join(elems[0:i])) | |
all_paths_sorted = sorted(all_paths_set) | |
# 出力作成 | |
# ### シンタックス毎の設定値 | |
link_format = " [{title}]({url})" | |
if syntax == "bl": | |
link_format = "[[{title}>{url}]]" | |
elif syntax == "org": | |
link_format = "[[{url}][{title}]]" | |
# ### 出力 | |
lines = [] | |
for path in all_paths_sorted: | |
title = (path.split("/"))[-1] | |
level = len(path.split("/")) | |
# wiki ページが存在する場合は リンクに変更 | |
if path in name_to_id: | |
url = "https://%s.backlog.jp/alias/wiki/%s" % ( | |
space, name_to_id[path]) | |
title = link_format.format(title=title, url=url) | |
lines.append(_item_line(title, level, syntax)) | |
return "\n".join(lines) | |
def _get_wikis(key: str, space: str, project: str) -> list: | |
"""wiki一覧を取得する | |
Args: | |
key (str): Backlog APIキー | |
space (str): Backlog スペースID | |
project (str): Backlog プロジェクトID もしくは プロジェクトキー | |
Returns: | |
list: wiki一覧 | |
""" | |
url = "https://%s.backlog.jp/api/v2/wikis" % space | |
param = "apiKey=%s&projectIdOrKey=%s" % (key, project) | |
try: | |
resp = requests.get("%s?%s" % (url, param)) | |
wikis = json.loads(resp.text) | |
if 'errors' in wikis: | |
print("An error occured: %s" % wikis, file=sys.stderr) | |
sys.exit(1) | |
except Exception as e: | |
print("An error occured: %s" % e, file=sys.stderr) | |
sys.exit(1) | |
return wikis | |
def get_backlog_wikis(key, space, project, syntax="md"): | |
"""wiki一覧の情報を取得して、テキスト(リスト形式)に出力します | |
Args: | |
key (str): Backlog APIキー | |
space (str): Backlog スペースID | |
project (str): Backlog プロジェクトID もしくは プロジェクトキー | |
syntax (str, optional): シンタックス(Markdown `md` or Backlog `bl` or Org-mode `org`) | |
""" | |
# wikiページ一覧の取得 | |
wikis = _get_wikis(key, space, project) | |
# 出力処理 | |
return _convert_to_text(space, wikis, syntax) | |
if __name__ == '__main__': | |
fire.Fire(get_backlog_wikis) |
以下にある Backlog API を使っています。
試してみる
使い方の表示 (--help
)
python get-backlog-wikis.py --help
でヘルプが出てきます。
特別な設定無しで、このような help 出力を作ってくれる Python Fire、素晴らしいです。
# python get-backlog-wikis.py --help INFO: Showing help with the command 'get-backlog-wikis.py -- --help'. NAME get-backlog-wikis.py - wiki一覧の情報を取得して、テキスト(リスト形式)に出力します SYNOPSIS get-backlog-wikis.py KEY SPACE PROJECT <flags> DESCRIPTION wiki一覧の情報を取得して、テキスト(リスト形式)に出力します POSITIONAL ARGUMENTS KEY Backlog APIキー SPACE Backlog スペースID PROJECT Backlog プロジェクトID もしくは プロジェクトキー FLAGS --syntax=SYNTAX Default: 'md' シンタックス(Markdown `md` or Backlog `bl` or Org-mode `org`) NOTES You can also use flags syntax for POSITIONAL ARGUMENTS
Wiki 一覧の取得
事前に必要なパラメータを準備しておきます。
# Backlog API キー KEY=KrGHymzEXAMPLE7748 # スペースID (参考: https://[スペースID].backlog.jp) SPACE=[スペースID] # プロジェクトID PROJECT=HOGE_PRJ
以下コマンドで Wiki 一覧を取得しましょう。
python get-backlog-wikis.py ${KEY} ${SPACE} ${PROJECT} # - [Home](https://${SPACE}.backlog.jp/alias/wiki/10752XXXXX) # - Kawahara # - [0_キックオフ](https://${SPACE}.backlog.jp/alias/wiki/10752XXXXX) # - 1_アカウント # - [AWS Organizations](https://${SPACE}.backlog.jp/alias/wiki/10752XXXXX) # - [Control Tower](https://${SPACE}.backlog.jp/alias/wiki/10752XXXXX) # - [アカウント戦略](https://${SPACE}.backlog.jp/alias/wiki/10752XXXXX) # (略)
他フォーマットで出力
--syntax
オプションで他フォーマットで出力します。
▼ Backlog 記法
python get-backlog-wikis.py ${KEY} ${SPACE} ${PROJECT} --syntax bl # - [[Home>https://${SPACE}.backlog.jp/alias/wiki/10752XXXXX]] # - Kawahara # -- [[0_キックオフ>https://${SPACE}.backlog.jp/alias/wiki/10752XXXXX]] # -- 1_アカウント # --- [[AWS Organizations>https://${SPACE}.backlog.jp/alias/wiki/10752XXXXX]] # ---- [[Control Tower>https://${SPACE}.backlog.jp/alias/wiki/10752XXXXX]] # --- [[アカウント戦略>https://${SPACE}.backlog.jp/alias/wiki/10752XXXXX]] # (略)
▼ Org-mode 記法
python get-backlog-wikis.py ${KEY} ${SPACE} ${PROJECT} --syntax org # - [[https://${SPACE}.backlog.jp/alias/wiki/10752XXXXX][Home]] # - Kawahara # - [[https://${SPACE}.backlog.jp/alias/wiki/10752XXXXX][0_キックオフ]] # - 1_アカウント # - [[https://${SPACE}.backlog.jp/alias/wiki/10752XXXXX][AWS Organizations]] # - [[https://${SPACE}.backlog.jp/alias/wiki/10752XXXXX][Control Tower]] # - [[https://${SPACE}.backlog.jp/alias/wiki/10752XXXXX][アカウント戦略]] # (略)
おわりに
Backlog API を試してみました。更新系の作業も API を使って色々と効率化できそうですね。
あと Python Fire はとても便利です。Pythonで自作CLI作っていきたいと 思っている方がいたら是非試してみてください。
参考
- GitHub - google/python-fire: Python Fire is a library for automatically generating command line interfaces (CLIs) from absolutely any Python object.
- Wikiページ一覧の取得 | Backlog Developer API | Nulab
- Pythonで簡単CLIツール作成。Python Fireを試してみた | DevelopersIO
実行環境
sw_vers # ProductName: macOS # ProductVersion: 11.6 # BuildVersion: 20G165 python --version # Python 3.7.3 pip list | grep fire # fire 0.4.0