作るもの
この回では、PART 07 の backlog_client.py を使い、チームの定例でそのまま使える 週次レポート を作る。
| シート | 内容 | 使いどころ |
|---|---|---|
| サマリー | プロジェクトごとの未完了件数・期限切れ件数・今週完了した件数 | 定例の冒頭で全体をつかむ |
| 担当者×状態 | 未完了課題を担当者と状態でクロス集計 | 負荷の偏りを見る |
| 期限切れ | 期限日を過ぎた未完了課題の一覧(古い順) | 要対応の課題を確認する |
| 予定と実績 | 今週完了した課題の、担当者別の予定時間と実績時間 | 見積もりの精度を振り返る |
| 未完了一覧 | 未完了課題の明細 | フィルターで深掘りする |
「今週」は実行日から7日前までとして数えるので、毎朝実行すれば常に直近1週間のレポートになる。あわせて要点を Google Chat に投稿し、Windows のタスクスケジューラで平日の朝に自動で実行する。
リクエスト数を抑える設計
定期実行では、毎回すべての課題を取り直すとレート制限(特に課題一覧が数えられる「検索」の枠)を無駄に使う。そこで次の方針をとる。
- 複数プロジェクトを1回の検索でまとめて取る:
projectId[]は複数指定できるので、プロジェクトごとに呼び分けない - 完了済みも含めて手元にキャッシュする:取得した課題を JSON ファイルに保存しておく
- 2回目以降は差分だけを取る:
updatedSinceで前回以降に更新された課題だけを取得し、キャッシュに上書きする - 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)。
"""複数プロジェクトの課題を集計し、週次レポート(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時より前に実行したときに、今日が期限の課題が期限切れと判定されることがある。
出力結果
> 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.xlsxExcel ファイルそのものはチャットに添付されないので、共有フォルダに出力する、ファイル名の代わりに共有フォルダのパスを書く、といった運用に合わせて chat_text を調整する。
毎朝自動で実行する
Windows のタスクスケジューラに登録する。仮想環境の Python を直接指定すると、有効化(Activate)の手順が不要になる。
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) | スクリプト プロパティ | スプレッドシートのシート |
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 = Dateconst 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言語の書き方の早見表、エラーコードと対処をまとめる。