BacklogAPI を Python から簡単に呼べるようにラップしたものです。
Python 3.5以上typingモジュールを使用しているため- 開発およびテスト環境は
Python 3.7.3を使用
詳細な仕様についてはドキュメントを参照してください
pip からインストールします。
pip install pybacklogpyドメイン及びシークレットキーを登録するには以下の2種類の方法があります。
- プログラム上で指定する
- 設定ファイルを置く
なお、どちらも設定していた場合、 プログラム上で指定する の方が優先されます。
Backlogのドメイン別に以下3種類のクラスを用意しています。
- BacklogComConfigure (backlog.com)
- BacklogJpConfigure (backlog.jp)
- BacklogToolConfigure (backlogtool.com)
このクラスのコンストラクタ引数として、スペースID と API のキーを渡すことで設定を行えます。
例えば、下記のような場合
- Backlogドメイン:
kitadakyou.backlog.com - API キー:
qwertyuiopasdfghjklzxcvbnmqazwsxedcrfvtgbyhnujmikolp
コードは次のようになります。
from pybacklogpy.BacklogConfigure import BacklogComConfigure
from pybacklogpy.Issue import Issue
# Configure クラスのインスタンスを生成
config = BacklogComConfigure(space_key='kitadakyou',
api_key='qwertyuiopasdfghjklzxcvbnmqazwsxedcrfvtgbyhnujmikolp')
issue_api = Issue(config) # API を呼ぶクラスのコンストラクタ引数として Configure クラスのインスタンスは使用可能
response = issue_api.get_issue_list()
使用するプロジェクトの直下に secrets というファイルを作り、以下のように値を入れておいてください。
なお、当プロジェクト直下にある secrets_sample をコピーすると楽です。
なお、このファイルは誤ってリポジトリにあげないよう、 .gitignore に追加しておくことを推奨します
[backlog]
Host = kitadakyou.backlog.com
ApiKey = qwertyuiopasdfghjklzxcvbnmqazwsxedcrfvtgbyhnujmikolpsecrets を指定した場合、先ほどの例で使用した configure クラスは省略して、以下のように書くことが出来ます
from pybacklogpy.Issue import Issue
issue_api_2 = Issue() # Configure クラスを渡さなかった場合は、設定ファイルの情報を読みに行く
response_2 = issue_api_2.get_issue_list()なお、 configure クラスを渡さず、 secrets も設置していない場合は実行エラーとなります。
使用するモジュールをロードします。 それぞれはクラスになっているので、そのインスタンスを生成します。
例として、Wiki の API を呼びたいと考えます。
from pybacklogpy.Wiki import Wiki
wiki_api = Wiki()どのような API があるかは PyBacklogPy のドキュメント、もしくは BacklogAPI のドキュメントを参照してください。 また、プロジェクトID や Wiki ID 等の調べ方は…ググればすぐに出てきます
Wiki を追加するサンプル
from pybacklogpy.Wiki import Wiki
wiki_api = Wiki()
response = wiki_api.add_wiki_page(
project_id=1000,
name='SampleWikiName',
content='サンプル Wiki 本文',
mail_notify=False,
)Wiki を更新するサンプル
from pybacklogpy.Wiki import Wiki
wiki_api = Wiki()
response = wiki_api.update_wiki_page(
wiki_id=12345,
name='TestWikiName',
content='テスト 本文',
mail_notify=False,
)全ての関数は request の レスポンスオブジェクト を返します。
リクエストが成功しているかを確認するには、 response.ok を見るのが１番早いです。
Wiki の更新が成功しているか確認するサンプル
from pybacklogpy.Wiki import Wiki
wiki_api = Wiki()
response = wiki_api.update_wiki_page(
wiki_id=12345,
name='TestWikiName',
content='テスト 本文',
mail_notify=False,
)
if not response.ok:
raise ValueError('Wiki の更新に失敗')また、レスポンス本文は response.text の中身に生(=テキストの)の JSON が入っています。標準ライブラリ json を使って parse してあげれば、簡単に使えます。
Wiki の内容を取得するサンプル
import json
from pybacklogpy.Wiki import Wiki
wiki_api = Wiki()
response = wiki_api.get_wiki_page(
wiki_id=12345,
)
if not response.ok:
raise ValueError('Wiki ページ情報の取得に失敗')
wiki_data = json.loads(response.text)
wiki_name = wiki_data['name']
wiki_content = wiki_data['content']ファイル取得については、特殊な返り値のため、別途こちらで説明します。
ファイルを取得する関数を使用する場合は、まずディレクトリを作成する必要があります。
デフォルトではプロジェクト直下の /tmp ディレクトリにファイルがダウンロードされます。(今の所、変更不可💦)
ファイルを取得する関数は「1番目がファイルのPATH」、「2番目がレスポンスオブジェクト」のタプルを返します。 そのため、一度に受け取るには、以下のように返り値を受け取る変数を2つ用意する必要があります。
from pybacklogpy.Wiki import Wiki
wiki_api = Wiki()
downloaded_file_path, response = self.wiki_attachment.get_wiki_page_attachment(
wiki_id=12345,
attachment_id=987654,
)
print(downloaded_file_path)自由にブランチを切って、 PullRequest を出してください。Issue を上げるだけでも大丈夫です。 一週間に一回くらいは見るようにするので、対応出来たら対応します。(全て対応するとは言っていない)
もし、PR出しても全くリアクションがない場合は Twitter の kitadakyou 、若しくは作者のメール宛にご連絡ください。
PyBacklog も BacklogPy も既に存在したので、苦肉の策で Py で挟みました。
もし、PyBacklogPy も存在したら、 PyBacklogXPyBacklog という HUNTER×HUNTER 方式で行こうと考えていました。