環境を準備する

Python 3.10 以降を前提にする。作業用のフォルダで仮想環境を作り、必要なライブラリを入れる。

PowerShell
mkdir backlog-fetch; cd backlog-fetch
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install requests pandas openpyxl
ライブラリ用途
requestsHTTP 通信
pandas集計と表の加工
openpyxlpandas から Excel(.xlsx)に書き出すときに使われる

接続先は PART 02 の環境変数(BACKLOG_HOST・BACKLOG_API_KEY・BACKLOG_PROJECT_KEY)から読む。

クライアントを作る

PART 04 で整理した「1回のリクエスト」「全件取得」を、再利用できるクラスにまとめる。PART 10 の実践でもこのファイルを使う。

Python(backlog_client.py)
"""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.0access_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 ファイルにする。

Python(open_issues.py)
"""指定プロジェクトの未完了課題を 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件ずつ受け取れる。

Python
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つずつダウンロードする。

Python
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 にもすぐ対応できる。依存が少ないページネーションや再試行を自分で書く(この回のクライアントで解決)
PyBacklogPyAPI ごとにメソッドがあり、引数の補完が効くコミュニティ製で、最終リリースは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 でスプレッドシートに定期的に取り込む方法も紹介する。

→ PART 08 — JavaScriptで取得する(Node.js・GAS)へ