作るもの

この回では、PART 07 の backlog_client.py を使い、チームの定例でそのまま使える 週次レポート を作る。

シート内容使いどころ
サマリープロジェクトごとの未完了件数・期限切れ件数・今週完了した件数定例の冒頭で全体をつかむ
担当者×状態未完了課題を担当者と状態でクロス集計負荷の偏りを見る
期限切れ期限日を過ぎた未完了課題の一覧(古い順)要対応の課題を確認する
予定と実績今週完了した課題の、担当者別の予定時間と実績時間見積もりの精度を振り返る
未完了一覧未完了課題の明細フィルターで深掘りする

「今週」は実行日から7日前までとして数えるので、毎朝実行すれば常に直近1週間のレポートになる。あわせて要点を Google Chat に投稿し、Windows のタスクスケジューラで平日の朝に自動で実行する。

リクエスト数を抑える設計

定期実行では、毎回すべての課題を取り直すとレート制限(特に課題一覧が数えられる「検索」の枠)を無駄に使う。そこで次の方針をとる。

  1. 複数プロジェクトを1回の検索でまとめて取る:projectId[] は複数指定できるので、プロジェクトごとに呼び分けない
  2. 完了済みも含めて手元にキャッシュする:取得した課題を JSON ファイルに保存しておく
  3. 2回目以降は差分だけを取る:updatedSince で前回以降に更新された課題だけを取得し、キャッシュに上書きする
  4. 7日に1回は全件を取り直す:差分では検出できない削除や、プロジェクトの移動を反映する

1,000件の課題があるスペースなら、全件取得は10回のリクエストだが、差分取得は多くの場合1〜2回で済む。公式ドキュメントのベストプラクティスでも、定期実行では結果をキャッシュし、updatedSince のような条件で取得件数を絞ることが推奨されている。

差分取得:updatedSince とキャッシュ

updatedSince は yyyy-MM-dd の日付で指定し、時刻は指定できない。そこで、前回の実行日から 1日さかのぼった日付 を指定して取りこぼしを防ぎ、重なって取れた課題は課題IDをキーに上書きする。

考え方
キャッシュ = { "last_sync": "2026-11-02", "issues": { "課題ID": 課題, … } }

前回の実行日がある → updatedSince = 前回の実行日 - 1日 で取得
前回の実行日がない、前回の全件取得から7日たった、または --full 指定 → 全件取得(キャッシュを作り直す)

取得した課題で キャッシュ["issues"][課題ID] を上書き
キャッシュ["last_sync"] = 今日

レポートスクリプト全体

backlog_client.py と同じフォルダに置く。対象のプロジェクトは環境変数 BACKLOG_PROJECT_KEYS にカンマ区切りで指定する(例:DEV,OPS)。

Python(weekly_report.py)
"""複数プロジェクトの課題を集計し、週次レポート(Excel)を作ってチャットに通知する

使い方:
  python weekly_report.py          … 差分取得してレポートを作る(7日ごとに自動で全件取得)
  python weekly_report.py --full   … 全件取得し直してからレポートを作る
"""
import json
import os
import sys
from datetime import date, timedelta
from pathlib import Path

import pandas as pd
import requests

from backlog_client import BacklogClient

HERE = Path(__file__).resolve().parent
CACHE_FILE = HERE / "cache" / "issues.json"
OUT_DIR = HERE / "reports"
DONE_STATUS_ID = 4
TODAY = date.today()


# ---------- 取得(差分+キャッシュ) ----------
def sync_issues(bl: BacklogClient, project_ids: list[int], full: bool) -> list[dict]:
    cache = {"last_sync": None, "last_full": None, "issues": {}}
    if CACHE_FILE.exists():
        cache = json.loads(CACHE_FILE.read_text(encoding="utf-8"))
    # 前回の全件取得から7日たっていたら、全件取り直す(削除やプロジェクト移動を反映するため)
    last_full = cache.get("last_full")
    if full or not last_full or date.fromisoformat(last_full) <= TODAY - timedelta(days=7):
        cache = {"last_sync": None, "last_full": None, "issues": {}}

    params = {"projectId[]": project_ids, "sort": "created", "order": "asc"}
    if cache["last_sync"]:
        since = date.fromisoformat(cache["last_sync"]) - timedelta(days=1)
        params["updatedSince"] = since.isoformat()
        print(f"差分取得: {since} 以降に更新された課題")
    else:
        print("全件取得")
        cache["last_full"] = TODAY.isoformat()

    fetched = bl.get_all("issues", params)
    for issue in fetched:
        cache["issues"][str(issue["id"])] = issue
    cache["last_sync"] = TODAY.isoformat()

    CACHE_FILE.parent.mkdir(exist_ok=True)
    CACHE_FILE.write_text(json.dumps(cache, ensure_ascii=False), encoding="utf-8")
    print(f"取得 {len(fetched)} 件 / キャッシュ {len(cache['issues'])} 件")
    # 対象外になったプロジェクトの課題は除く
    return [i for i in cache["issues"].values() if i["projectId"] in project_ids]


# ---------- 表に変換 ----------
def to_frame(issues: list[dict]) -> pd.DataFrame:
    df = pd.DataFrame([{
        "プロジェクト": i["issueKey"].rsplit("-", 1)[0],
        "課題キー": i["issueKey"],
        "件名": i["summary"],
        "状態ID": i["status"]["id"],
        "状態": i["status"]["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.to_datetime(df["期限日"]).dt.date
    df["更新日時"] = (pd.to_datetime(df["更新日時"], utc=True)
                      .dt.tz_convert("Asia/Tokyo").dt.tz_localize(None))
    return df


# ---------- 集計 ----------
def build_report(df: pd.DataFrame) -> dict[str, pd.DataFrame]:
    week_ago = pd.Timestamp(TODAY - timedelta(days=7))
    open_df = df[df["状態ID"] != DONE_STATUS_ID]
    overdue = open_df[open_df["期限日"].notna() & (open_df["期限日"] < TODAY)]
    # 今週完了:状態が完了で、この7日間に更新されたもの(完了にした操作も更新に含まれる)
    done_week = df[(df["状態ID"] == DONE_STATUS_ID) & (df["更新日時"] >= week_ago)]

    summary = pd.DataFrame({
        "未完了": open_df.groupby("プロジェクト").size(),
        "期限切れ": overdue.groupby("プロジェクト").size(),
        "今週完了": done_week.groupby("プロジェクト").size(),
    }).fillna(0).astype(int)
    summary.loc["合計"] = summary.sum()

    by_status = pd.crosstab(open_df["担当者"], open_df["状態"], margins=True, margins_name="合計")
    by_status = pd.concat([by_status.drop(index="合計").sort_values("合計", ascending=False),
                           by_status.loc[["合計"]]])          # 合計の行は最後に

    est_vs_act = (done_week.groupby("担当者")
                  .agg(完了件数=("課題キー", "count"),
                       予定時間=("予定時間", "sum"),
                       実績時間=("実績時間", "sum"))
                  .sort_values("完了件数", ascending=False))
    est_vs_act["差(実績-予定)"] = est_vs_act["実績時間"] - est_vs_act["予定時間"]
    est_vs_act["実績/予定"] = (est_vs_act["実績時間"] / est_vs_act["予定時間"]
                              .where(est_vs_act["予定時間"] > 0)).round(2)

    cols = ["課題キー", "件名", "状態", "担当者", "期限日", "予定時間", "実績時間", "更新日時"]
    return {
        "サマリー": summary,
        "担当者×状態": by_status,
        "期限切れ": overdue.sort_values("期限日")[cols],
        "予定と実績": est_vs_act,
        "未完了一覧": open_df.sort_values(["担当者", "期限日"])[cols],
    }


# ---------- 出力 ----------
def write_excel(report: dict[str, pd.DataFrame]) -> Path:
    OUT_DIR.mkdir(exist_ok=True)
    path = OUT_DIR / f"backlog_weekly_{TODAY:%Y%m%d}.xlsx"
    with pd.ExcelWriter(path) as xw:
        for name, frame in report.items():
            index = name in ("サマリー", "担当者×状態", "予定と実績")
            frame.to_excel(xw, sheet_name=name, index=index)
    return path


def chat_text(report: dict[str, pd.DataFrame], path: Path) -> str:
    s = report["サマリー"].loc["合計"]
    lines = [f"*Backlog 週次レポート({TODAY:%m/%d})*",
             f"未完了 {s['未完了']} 件 / 期限切れ {s['期限切れ']} 件 / 今週完了 {s['今週完了']} 件"]
    top = report["期限切れ"].head(5)
    if not top.empty:
        lines.append("期限切れ(古い順):")
        lines += [f"- {r.課題キー} {r.件名}({r.担当者}、期限 {r.期限日})" for r in top.itertuples()]
    lines.append(f"詳細: {path.name}")
    return "\n".join(lines)


def notify(text: str) -> None:
    url = os.environ.get("GCHAT_WEBHOOK_URL")
    if not url:
        print(text)
        return
    requests.post(url, json={"text": text}, timeout=10).raise_for_status()


def main() -> None:
    full = "--full" in sys.argv
    keys = [k.strip() for k in os.environ["BACKLOG_PROJECT_KEYS"].split(",") if k.strip()]
    bl = BacklogClient()
    project_ids = [bl.project_id(k) for k in keys]

    issues = sync_issues(bl, project_ids, full)
    if not issues:
        print("対象の課題がありません")
        return
    df = to_frame(issues)
    report = build_report(df)
    path = write_excel(report)
    print(f"出力: {path}")
    notify(chat_text(report, path))


if __name__ == "__main__":
    main()

集計のポイント

複数プロジェクトの状態

この回では完了済みの課題もキャッシュするため、状態で絞り込まずに取得し、手元で「状態ID が 4 かどうか」で未完了と完了を分けている。プロジェクトごとにカスタム状態が違っていても、既定の「完了」の ID は共通なので、この判定で横断集計ができる。

「今週完了」の判定

課題の JSON には「完了にした日時」という項目がない。ここでは「状態が完了で、更新日時がこの7日以内」を今週完了とみなしている。完了後にコメントを付けただけでも更新日時は変わるので、厳密に数えたい場合は、PART 07 のコメントの changeLog から、状態が「完了」に変わった日時を調べる。

予定と実績の比較

予定時間が未入力(0 や null)の課題が多いと、比率が意味を持たない。実績/予定 の列は予定時間が0より大きい担当者だけを計算し、それ以外は空欄にしている。この列が極端に大きい・小さい担当者がいれば、見積もりの前提を見直すきっかけになる。

期限切れ

期限日は「日付だけ」を使って今日と比べている(PART 04)。日時として比べると、日本時間の午前9時より前に実行したときに、今日が期限の課題が期限切れと判定されることがある。

出力結果

実行例(2回目以降)
> python weekly_report.py
差分取得: 2026-11-01 以降に更新された課題
取得 46 件 / キャッシュ 1284 件
出力: C:\work\backlog-fetch\reports\backlog_weekly_20261109.xlsx
サマリー シートの例
プロジェクト  未完了  期限切れ  今週完了
DEV            237       18        31
OPS             64        3        12
合計           301       21        43
予定と実績 シートの例
担当者      完了件数  予定時間  実績時間  差(実績-予定)  実績/予定
佐藤 花子       12      30.0      34.5            4.5       1.15
山田 太郎        9      24.0      21.0           -3.0       0.88
鈴木 一郎        8      12.0      26.0           14.0       2.17

チャットに通知する

環境変数 GCHAT_WEBHOOK_URL に Google Chat の Incoming Webhook の URL を設定すると、レポートの要点がスペースに投稿される(未設定ならコンソールに表示するだけ)。Webhook の作り方と、見出しやボタンのあるカード形式での送り方は、Google Chat Bot自動投稿シリーズ で解説している。

投稿される内容の例
*Backlog 週次レポート(11/09)*
未完了 301 件 / 期限切れ 21 件 / 今週完了 43 件
期限切れ(古い順):
- DEV-87 帳票出力のレイアウト修正(鈴木 一郎、期限 2026-10-15)
- OPS-41 監視設定の見直し((未割り当て)、期限 2026-10-20)
…
詳細: backlog_weekly_20261109.xlsx

Excel ファイルそのものはチャットに添付されないので、共有フォルダに出力する、ファイル名の代わりに共有フォルダのパスを書く、といった運用に合わせて chat_text を調整する。

毎朝自動で実行する

Windows のタスクスケジューラに登録する。仮想環境の Python を直接指定すると、有効化(Activate)の手順が不要になる。

PowerShell(管理者でなくてよい)
schtasks /Create /SC WEEKLY /D MON,TUE,WED,THU,FRI /ST 08:30 /TN "Backlog週次レポート" `
  /TR "C:\work\backlog-fetch\.venv\Scripts\python.exe C:\work\backlog-fetch\weekly_report.py"
  • 環境変数(BACKLOG_HOST など)は、PART 02 の方法で ユーザー環境変数 に保存しておく。タスクは登録したユーザーとして動くので、その値が使われる
  • スクリプトはキャッシュとレポートの場所を __file__ 基準で決めているので、作業フォルダの設定は不要だ
  • PC がスリープしていると実行されない。「スケジュールされた時刻にタスクを開始できなかった場合、すぐにタスクを実行する」をタスクのプロパティで有効にしておく

タスクスケジューラの詳しい設定や、AWS Lambda など PC 以外で動かす方法は、Google Chat Bot自動投稿 PART 04 でまとめている。

VBA・GAS で差分取得する場合

考え方は同じで、「前回の実行日」をどこに保存するかが違うだけだ。

言語前回の実行日の保存先キャッシュの保存先
Excel VBA(PART 06)「設定」シートのセル「課題一覧」シート自体(課題キーで行を探して上書きし、なければ追加)
GAS(PART 08)スクリプト プロパティスプレッドシートのシート
VBA(PART 06 のマクロに追加する部分)
Dim lastSync As Variant
lastSync = ThisWorkbook.Worksheets("設定").Range("B4").Value      ' 前回の実行日
If IsDate(lastSync) Then
    q = q & "&updatedSince=" & Format$(CDate(lastSync) - 1, "yyyy-mm-dd")
End If
' … 取得してシートを更新したあと …
ThisWorkbook.Worksheets("設定").Range("B4").Value = Date
Apps Script(PART 08 の fetchOpenIssues に追加する部分)
const last = PROPS.getProperty('LAST_SYNC');                   // 'yyyy-MM-dd'
const params = { 'projectId[]': project.id, sort: 'created', order: 'asc' };
if (last) {
  const since = new Date(last);
  since.setDate(since.getDate() - 1);
  params.updatedSince = Utilities.formatDate(since, 'Asia/Tokyo', 'yyyy-MM-dd');
}
// … 取得してシートを更新したあと …
PROPS.setProperty('LAST_SYNC', Utilities.formatDate(new Date(), 'Asia/Tokyo', 'yyyy-MM-dd'));

差分で取った課題は「未完了から完了に変わったもの」も含むので、シートを更新するときは状態を見て、完了になった行を消す(または完了の印を付ける)処理を入れる。

運用で気をつけること

気をつけること理由と対策
削除された課題がキャッシュに残る差分取得では削除を検出できない。スクリプトでは前回の全件取得から7日たつと自動で全件取得して作り直す
初回の全件取得が重い課題が数万件あると数百回のリクエストになる。初回は時間に余裕のあるときに手動で実行する
キャッシュに課題の内容が残る件名や説明がファイルに保存される。キャッシュとレポートのフォルダは、プロジェクトのメンバー以外が読めない場所に置く
集計用ユーザーの権限取得できるのはキーを発行したユーザーが参加しているプロジェクトだけ。対象のプロジェクトを増やしたら、そのユーザーも参加させる
実行に失敗しても気づかない例外が起きたときにもチャットへ通知する、タスクスケジューラの「前回の実行結果」を定期的に見る

✅ 次の記事では…

PART 11(付録)では、Backlog API で取得できる情報の一覧、「やりたいこと → API」の逆引き、5言語の書き方の早見表、エラーコードと対処をまとめる。

→ PART 11 — 付録:取得できる情報一覧と逆引きへ