環境を準備する
Python 3.10 以降を前提にする。作業用のフォルダで仮想環境を作り、必要なライブラリを入れる。
mkdir backlog-fetch; cd backlog-fetch
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install requests pandas openpyxl| ライブラリ | 用途 |
|---|---|
requests | HTTP 通信 |
pandas | 集計と表の加工 |
openpyxl | pandas から Excel(.xlsx)に書き出すときに使われる |
接続先は PART 02 の環境変数(BACKLOG_HOST・BACKLOG_API_KEY・BACKLOG_PROJECT_KEY)から読む。
クライアントを作る
PART 04 で整理した「1回のリクエスト」「全件取得」を、再利用できるクラスにまとめる。PART 10 の実践でもこのファイルを使う。
"""Backlog API v2 を呼ぶための小さなクライアント"""
from __future__ import annotations
import os
import time
from collections.abc import Iterator
from pathlib import Path
from typing import Any
import requests
class BacklogError(Exception):
"""Backlog API がエラーを返したときの例外"""
def __init__(self, status: int, code: int | None, message: str, url: str):
super().__init__(f"HTTP {status} (code={code}): {message} [{url}]")
self.status, self.code, self.message, self.url = status, code, message, url
class BacklogClient:
RETRY_STATUSES = {429, 500, 502, 503, 504}
def __init__(self, host: str | None = None, api_key: str | None = None,
access_token: str | None = None, timeout: float = 30.0, max_retries: int = 5):
self.base_url = f"https://{host or os.environ['BACKLOG_HOST']}/api/v2/"
self.timeout = timeout
self.max_retries = max_retries
self.session = requests.Session()
if access_token: # OAuth 2.0(PART 03)
self.session.headers["Authorization"] = f"Bearer {access_token}"
else: # APIキー(PART 02)
self.session.headers["Backlog-API-Key"] = api_key or os.environ["BACKLOG_API_KEY"]
# ---- 1回のリクエスト ----
def request(self, path: str, params: dict | None = None, stream: bool = False) -> requests.Response:
url = self.base_url + path.lstrip("/")
for attempt in range(1, self.max_retries + 1):
try:
resp = self.session.get(url, params=params, timeout=self.timeout, stream=stream)
except (requests.ConnectionError, requests.Timeout):
if attempt == self.max_retries:
raise
time.sleep(5 * attempt)
continue
if resp.status_code in self.RETRY_STATUSES and attempt < self.max_retries:
wait = self._seconds_until_reset(resp) if resp.status_code == 429 else 5 * attempt
print(f"HTTP {resp.status_code}: {wait:.0f}秒待って再試行します({attempt}回目)")
time.sleep(wait)
continue
if not resp.ok:
raise self._to_error(resp)
self._wait_if_limit_low(resp)
return resp
raise RuntimeError("再試行の上限に達しました") # ここには来ない
def get(self, path: str, params: dict | None = None) -> Any:
return self.request(path, params).json()
# ---- 全件取得:count / offset ----
def get_all(self, path: str, params: dict | None = None, page_size: int = 100) -> list[dict]:
params = dict(params or {})
params["count"] = page_size
offset, items = 0, []
while True:
params["offset"] = offset
page = self.get(path, params)
items.extend(page)
if len(page) < page_size:
return items
offset += page_size
# ---- 全件取得:minId(コメント・活動・通知など) ----
def iter_by_min_id(self, path: str, params: dict | None = None, page_size: int = 100) -> Iterator[dict]:
params = dict(params or {}) | {"count": page_size, "order": "asc"}
while True:
page = self.get(path, params)
yield from page
if len(page) < page_size:
return
params["minId"] = page[-1]["id"]
# ---- ファイルのダウンロード ----
def download(self, path: str, dest_dir: str | Path) -> Path:
resp = self.request(path, stream=True)
name = _filename_from(resp) or path.rsplit("/", 1)[-1]
dest = Path(dest_dir) / name
dest.parent.mkdir(parents=True, exist_ok=True)
with open(dest, "wb") as f:
for chunk in resp.iter_content(chunk_size=64 * 1024):
f.write(chunk)
return dest
# ---- 内部処理 ----
@staticmethod
def _seconds_until_reset(resp: requests.Response) -> float:
reset = resp.headers.get("X-RateLimit-Reset")
if reset and reset.isdigit():
return max(1.0, int(reset) - time.time() + 1)
return 60.0 # わからなければ1分待つ
def _wait_if_limit_low(self, resp: requests.Response) -> None:
remaining = resp.headers.get("X-RateLimit-Remaining")
if remaining is not None and remaining.isdigit() and int(remaining) <= 1:
wait = self._seconds_until_reset(resp)
print(f"レート制限の残りが少ないため {wait:.0f}秒待ちます")
time.sleep(wait)
@staticmethod
def _to_error(resp: requests.Response) -> BacklogError:
code, message = None, resp.reason
try:
err = resp.json()["errors"][0]
code, message = err.get("code"), err.get("message", message)
except (ValueError, KeyError, IndexError, TypeError):
if resp.status_code == 401 and "WWW-Authenticate" in resp.headers:
message = resp.headers["WWW-Authenticate"] # OAuth 2.0 の認証エラー
return BacklogError(resp.status_code, code, message, resp.url)
# ---- よく使う変換 ----
def project_id(self, project_key: str) -> int:
return self.get(f"projects/{project_key}")["id"]
def open_status_ids(self, project_key: str, done_ids: tuple[int, ...] = (4,)) -> list[int]:
"""「完了」以外の状態IDを返す(カスタム状態も含む)"""
return [s["id"] for s in self.get(f"projects/{project_key}/statuses") if s["id"] not in done_ids]
def _filename_from(resp: requests.Response) -> str | None:
"""Content-Disposition からファイル名を取り出す(filename*=UTF-8'' 形式にも対応)"""
from email.message import Message
cd = resp.headers.get("Content-Disposition")
if not cd:
return None
msg = Message()
msg["Content-Disposition"] = cd
name = msg.get_filename()
return Path(name).name if name else Noneクライアントのポイント
| 処理 | 内容 |
|---|---|
requests.Session | ヘッダーを1回設定すれば全リクエストに付く。接続も再利用されるので、何百回も呼ぶときに速い |
| APIキーと OAuth 2.0 | access_token を渡すと Authorization: Bearer に切り替わる。PART 03 の get_access_token() の戻り値をそのまま渡せる |
| 429 の再試行 | X-RateLimit-Reset の時刻まで待ってから再送する。5xx と通信エラーは少しずつ待ち時間を延ばす |
| 先回りの待機 | 成功したレスポンスでも X-RateLimit-Remaining が1以下なら、次を送る前にリセットまで待つ |
| エラーの例外 | errors[0] の code と message を BacklogError に入れる。呼び出し側で e.code == 6 などと判定できる |
| 配列パラメータ | params={"statusId[]": [1, 2, 3]} とリストで渡せば、requests が statusId[]=1&statusId[]=2&… に展開する |
お題:未完了課題を Excel に出力する
クライアントを使って お題 を実装する。結果は「課題一覧」「担当者別」の2シートを持つ Excel ファイルにする。
"""指定プロジェクトの未完了課題を Excel に出力し、担当者別の件数を表示する"""
import os
import sys
import pandas as pd
from backlog_client import BacklogClient
JST = "Asia/Tokyo"
def to_rows(issues: list[dict]) -> pd.DataFrame:
rows = [{
"課題キー": i["issueKey"],
"件名": i["summary"],
"種別": i["issueType"]["name"],
"状態": i["status"]["name"],
"優先度": i["priority"]["name"],
"担当者": (i.get("assignee") or {}).get("name", "(未割り当て)"),
"期限日": (i.get("dueDate") or "")[:10] or None, # 日付だけを使う
"予定時間": i.get("estimatedHours"),
"実績時間": i.get("actualHours"),
"更新日時": i["updated"],
} for i in issues]
df = pd.DataFrame(rows)
if df.empty:
return df
df["期限日"] = pd.to_datetime(df["期限日"]).dt.date
# UTC → 日本時間。Excel はタイムゾーン付きの日時を書けないので tz を外す
df["更新日時"] = pd.to_datetime(df["更新日時"], utc=True).dt.tz_convert(JST).dt.tz_localize(None)
return df
def main(project_key: str) -> None:
bl = BacklogClient()
params = {
"projectId[]": [bl.project_id(project_key)],
"statusId[]": bl.open_status_ids(project_key),
"sort": "created",
"order": "asc",
}
print(f"対象: {bl.get('issues/count', params)['count']} 件")
issues = bl.get_all("issues", params)
issues = list({i["id"]: i for i in issues}.values()) # 念のため重複を除く
df = to_rows(issues)
if df.empty:
print("未完了の課題はありません")
return
summary = (df.groupby("担当者")
.agg(未完了件数=("課題キー", "count"), 予定時間の合計=("予定時間", "sum"))
.sort_values("未完了件数", ascending=False))
out = f"issues_{project_key}.xlsx"
with pd.ExcelWriter(out) as xw:
df.to_excel(xw, sheet_name="課題一覧", index=False)
summary.to_excel(xw, sheet_name="担当者別")
print(f"出力: {out}({len(df)}件)")
print(summary.to_string())
if __name__ == "__main__":
main(sys.argv[1] if len(sys.argv) > 1 else os.environ["BACKLOG_PROJECT_KEY"])> python open_issues.py DEV
対象: 237 件
出力: issues_DEV.xlsx(237件)
未完了件数 予定時間の合計
担当者
佐藤 花子 64 182.5
山田 太郎 51 140.0
鈴木 一郎 48 96.0
(未割り当て) 41 0.0
高橋 次郎 33 77.5最初に issues/count で件数を数えているのは、何回リクエストすることになるかの目安を出すためだ。件数だけ必要な集計なら、get_all を呼ばずに issues/count だけで済ませると、検索の枠を大きく節約できる。
💡 CSV で出したい場合
df.to_csv("issues.csv", index=False, encoding="utf-8-sig") とする。utf-8-sig は BOM 付きの UTF-8 で、Excel でそのまま開いても文字化けしない。
コメントを取得する
課題のコメントは offset ではなく minId で続きを取る(PART 04)。クライアントの iter_by_min_id を使えば、件数を気にせず1件ずつ受け取れる。
from backlog_client import BacklogClient
bl = BacklogClient()
for c in bl.iter_by_min_id("issues/DEV-123/comments"):
who = c["createdUser"]["name"]
text = (c.get("content") or "").replace("\n", " ")[:60]
changes = ", ".join(f'{x["field"]}: {x["originalValue"]} → {x["newValue"]}'
for x in c.get("changeLog") or [])
print(c["created"], who, text, f"[{changes}]" if changes else "")状態や担当者を変更したときの履歴は、本文が空のコメントとして記録され、changeLog に「どの項目が何から何に変わったか」が入る。これを使うと「処理中になった日時」「完了になった日時」を課題ごとに調べられる。
⚠️ 全課題のコメントを取ると、すぐにレート制限に近づく
コメントは課題ごとに API を呼ぶ必要がある。500件の課題なら最低500回だ。対象を「今週更新された課題」などに絞るか、PART 10 の差分取得と組み合わせる。
添付ファイルをダウンロードする
課題の添付ファイルは、一覧で ID を調べてから1つずつダウンロードする。
from backlog_client import BacklogClient
bl = BacklogClient()
issue_key = "DEV-123"
for a in bl.get(f"issues/{issue_key}/attachments"):
path = bl.download(f"issues/{issue_key}/attachments/{a['id']}", f"attachments/{issue_key}")
print(f"{a['name']} ({a['size']:,} bytes) → {path}")ダウンロードの応答では、ファイル名が Content-Disposition ヘッダーに入っている。日本語のファイル名は filename*=UTF-8''… の形でエンコードされているため、クライアントの _filename_from では標準ライブラリの email.message で正しく取り出している。同じ形の API で、Wiki の添付ファイル(wikis/{ID}/attachments/{添付ID})や共有ファイル(projects/{キー}/files/{ID})も取得できる。
既存のライブラリとの比較
Python には Backlog API 用のライブラリもいくつかある。
| 方法 | 長所 | 短所 |
|---|---|---|
| requests で直接呼ぶ(この回) | 公式ドキュメントのパラメータ名がそのまま使える。新しい API にもすぐ対応できる。依存が少ない | ページネーションや再試行を自分で書く(この回のクライアントで解決) |
| PyBacklogPy | API ごとにメソッドがあり、引数の補完が効く | コミュニティ製で、最終リリースは2021年。新しい API やヘッダーでのキー指定には対応していない |
| BacklogPy、pybacklog など | 薄いラッパーで書き方が簡単 | 同じくコミュニティ製で、更新頻度が低い |
Backlog API は URL とパラメータの規則が素直なので、ライブラリを使わなくても十分に書きやすい。公式のライブラリがある JavaScript(PART 08)や Java(PART 09)とは事情が違う点に注意したい。
つまずきやすい点
| 症状 | 原因と対処 |
|---|---|
KeyError: 'BACKLOG_HOST' | 環境変数が設定されていない。ターミナルを開き直したか確認する |
TypeError: 'NoneType' object is not subscriptable | 担当者がいない課題で i["assignee"]["name"] と書いている。(i.get("assignee") or {}).get("name") にする |
Excel does not support datetimes with timezones | タイムゾーン付きの日時を Excel に書こうとしている。.dt.tz_localize(None) で外す |
| 状態で絞り込んだのに全部の課題が返る | パラメータ名を statusId と書いている。[] を付けて statusId[] にする |
| 実行が途中で止まったように見える | レート制限で待機している。表示されるメッセージを確認する |
✅ 次の記事では…
PART 08 では、公式 SDK の backlog-js を使って Node.js でお題を実装し、Google Apps Script でスプレッドシートに定期的に取り込む方法も紹介する。