Backlog APIを使って Wiki 一覧(リンク付き)を取得する Python製 CLIを作ってみる

Backlog APIを使って Wiki 一覧(リンク付き)を取得する Python製 CLIを作ってみる

Clock Icon2021.11.08

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

はじめに

『Backlog Wiki で今まで作ってきたページ一覧をさくっと取得したいな…』 とふと思い作ってみました。

以下のような利用イメージです。

▼ 実行コマンド

python get-backlog-wikis.py ${APIKEY} ${SPACE} ${PROJECT} --syntax md

▼ 取得できるテキスト例

img

▼ 取得できるテキスト例 (Markdown プレビュー)

img

事前準備

Python Fire 導入

GitHub - google/python-fire

Python Fire は Python製 CLIを簡単に作ることができるツールです。 今回はこれを使います。

弊社ブログに紹介ブログがあるので詳しくは以下を参照ください。

私は Mac 環境なので 以下コマンドで Python Fire をインストールしました。

pip install fire

Backlog APIキー 取得

APIキーを取得しておきましょう。 Backlog の [個人設定 > API] から取得できます。

img

スクリプトを書いてみる

以下 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作っていきたいと 思っている方がいたら是非試してみてください。

参考

実行環境

sw_vers
# ProductName:	macOS
# ProductVersion:	11.6
# BuildVersion:	20G165

python --version
# Python 3.7.3

pip list | grep fire
# fire                  0.4.0

Share this article

facebook logohatena logotwitter logo

© Classmethod, Inc. All rights reserved.