なぜ API で取得するのか
Backlog の画面には課題の検索や CSV 出力があるが、実務では次のような場面ですぐに限界が来る。
- 毎週の定例で「担当者別の未完了件数」「期限切れの課題」を同じ形式で出したい
- 複数プロジェクトをまたいで、予定時間と実績時間を集計したい
- 課題の一覧を Excel に貼り付け、別の管理表と突き合わせたい
- コメントや添付ファイルまで含めてバックアップしておきたい
どれも「画面で検索 → CSV 出力 → Excel で加工」を手で繰り返せばできるが、毎回の手作業は抜け漏れの元になる。Backlog API を使えば、この一連の作業をスクリプト1本にまとめ、ボタン1つやタスクスケジューラで再実行できるようになる。
このシリーズは 情報の取得(読み取り) に絞る。課題の登録や更新も同じ API でできるが、取得だけなら誤操作でデータを壊す心配がなく、最初の一歩として安全だ。
Backlog API の基本構造
Backlog API(現行は v2)は、HTTPS で JSON を返す REST API だ。URL は次の形をしている。
https://{スペースID}.backlog.com/api/v2/{リソース}
https://{スペースID}.backlog.jp/api/v2/{リソース}
例)https://example.backlog.com/api/v2/issues?projectId[]=12345&count=100| 部分 | 意味 |
|---|---|
| スペースID | Backlog にログインするときの URL の先頭部分(example.backlog.com なら example) |
| ドメイン | 契約によって backlog.com・backlog.jp・backlogtool.com のいずれか。ブラウザで開いている URL と同じものを使う |
/api/v2/ | API のバージョン。以降のパスで取得したいリソースを指定する |
| クエリ文字列 | 絞り込み条件や件数。projectId[] のように [] の付いた名前は、同じ名前を繰り返して複数の値を渡す |
レスポンスは UTF-8 の JSON で、一覧系の API は配列、単体の API はオブジェクトを返す。日時は 2026-11-05T01:23:45Z のような UTC の ISO 8601 形式なので、日本時間で表示するには9時間足す必要がある(各言語の回で変換方法を示す)。
💡 ドメインを間違えると「認証エラー」になる
APIキーが正しくても、backlog.jp のスペースに backlog.com でアクセスすると認証に失敗する。最初につまずく原因の多くはこれだ。ブラウザのアドレスバーに表示されている URL をそのまま使うのが確実だ。
取得できる情報の地図
Backlog の画面で見られる情報のほとんどは API で取得できる。よく使うものを整理すると次のようになる。
| 分類 | 主な情報 | 代表的な API |
|---|---|---|
| スペース | スペース名、最近の更新、容量の使用状況 | /space、/space/activities |
| プロジェクト | プロジェクト一覧、種別・カテゴリー・マイルストーン・状態・カスタム属性 | /projects、/projects/{キー}/statuses |
| 課題 | 件名・状態・担当者・期限・予定/実績時間・カスタム属性 | /issues、/issues/count、/issues/{課題キー} |
| 課題の付随情報 | コメント(変更履歴を含む)、添付ファイル、関連する共有ファイル | /issues/{課題キー}/comments、/attachments |
| Wiki・ドキュメント | ページ一覧と本文、タグ、履歴、添付ファイル | /wikis、/wikis/{ID}、/documents |
| ファイル | 共有ファイルの一覧とダウンロード | /projects/{キー}/files/metadata/{パス} |
| Git | リポジトリ、プルリクエストとそのコメント | /projects/{キー}/git/repositories、.../pullRequests |
| ユーザー・チーム | 自分の情報、プロジェクトメンバー、チーム | /users/myself、/projects/{キー}/users |
| 通知・ウォッチ | 自分宛ての通知、ウォッチ中の課題 | /notifications、/users/{ID}/watchings |
全体の一覧と「やりたいこと → API」の逆引きは PART 11(付録) にまとめている。
なお、取得できる範囲は API を呼ぶユーザーの権限と同じ だ。自分が参加していないプロジェクトの課題は、API でも見えない。管理者ユーザーで全プロジェクトを集計するのか、自分の担当分だけを取るのかで、使うアカウントが変わる。
認証方式は2つ:APIキーと OAuth 2.0
Backlog API を呼ぶには、「誰としてアクセスするか」を示す認証情報が必要だ。方式は2つある。
| APIキー | OAuth 2.0 | |
|---|---|---|
| 取得方法 | Backlog の個人設定で発行(1分で終わる) | Backlog Developer サイトでアプリを登録し、ブラウザでの許可を経てトークンを取得 |
| 渡し方 | ヘッダー Backlog-API-Key(推奨)またはクエリ apiKey= | ヘッダー Authorization: Bearer {アクセストークン} |
| 有効期限 | 削除するまで有効 | アクセストークンは1時間。リフレッシュトークンで更新する |
| 向いている用途 | 自分用・チーム内の集計スクリプト、Excel マクロ、定期バッチ | 複数の利用者がそれぞれ自分のアカウントで使う Web アプリやツール |
| この連載 | PART 02 で発行。PART 05 以降の基本 | PART 03 で解説 |
社内で使う集計スクリプトなら APIキーで十分だ。一方、「各メンバーが自分の課題を見るツール」を作って配るなら、利用者ごとにキーを発行してもらうより、OAuth 2.0 で各自に許可してもらう方が安全で手間も少ない。
最初に知っておきたい制約
1回で取れるのは最大100件
課題一覧などの API は、1回のリクエストで返す件数が既定で20件、最大でも100件だ。1,000件の課題を取るには、offset をずらしながら10回呼ぶ必要がある(ページネーション)。この処理は全言語で必ず書くことになるので、PART 04 で詳しく扱う。
1分あたりのリクエスト数に上限がある
Backlog API には ユーザーごと・1分あたり のリクエスト数の上限(レート制限)がある。上限は「読み込み」「更新」「検索」「アイコン」の種別とプランによって分かれていて、課題一覧の取得は「検索」に数えられる。上限を超えると HTTP 429 が返る。
- 上限は APIキー単位ではなくユーザー単位。キーを2つ作っても枠は増えない
- 現在の上限と残り回数は、レスポンスヘッダーか
/api/v2/rateLimitで確認できる - 課題ごとにコメントを取るような処理は、すぐに上限に近づく
具体的な値はプランや負荷で変わるため、この連載ではヘッダーを見て待つ書き方を基本にする。
どの言語で取得するか
Backlog API は HTTP と JSON だけで呼べるので、言語は何でもよい。この連載では、現場でよく使われる5系統を同じお題で比べる。
| 言語・ツール | 向いている場面 | 回 |
|---|---|---|
| curl・PowerShell | まず試す、1回限りの調査、Windows 標準機能だけで CSV を出したい | PART 05 |
| Excel VBA | 結果を Excel のシートで見たい、マクロ付きブックで配りたい | PART 06 |
| Python | 集計・加工が多い、Excel 出力や定期実行まで含めて自動化したい | PART 07 |
| JavaScript(Node.js・GAS) | 公式 SDK を使いたい、Google スプレッドシートに定期的に取り込みたい | PART 08 |
| Java | 既存の Java システムやバッチに組み込みたい | PART 09 |
公式(Nulab 提供)のライブラリは JavaScript 用の backlog-js と Java 用の Backlog4j がある。Python にもコミュニティ製のライブラリはあるが、更新が止まっているものが多いため、この連載では requests で直接呼ぶ方法を基本にする。
迷ったら、試すのは PowerShell、続けて使うなら Python、Excel で配るなら VBA と考えるとよい。
このシリーズの進め方
- 準備(PART 02〜04):APIキーの発行と接続確認、OAuth 2.0、全言語に共通する基本パターン
- 言語別(PART 05〜09):同じお題「指定プロジェクトの未完了課題を担当者別に一覧化する」を各言語で実装
- 実践(PART 10):複数プロジェクトの集計、予定と実績の比較、差分取得、定期レポート
- 付録(PART 11):取得できる情報の一覧、言語別の早見表、エラーと対処
言語別の回はどれから読んでもよいように、共通の考え方は PART 04 にまとめ、各回では書き方の違いに集中する。接続先は環境変数で渡す形にそろえる。
BACKLOG_HOST 例)example.backlog.com(https:// は付けない)
BACKLOG_API_KEY PART 02 で発行した APIキー
BACKLOG_PROJECT_KEY 例)DEV(課題キー DEV-123 の「DEV」の部分)✅ 次の記事では…
PART 02 では APIキーを発行し、curl と PowerShell で自分のユーザー情報を取得して接続を確認する。キーを安全に保管する方法もあわせて扱う。