なぜ API で取得するのか

Backlog の画面には課題の検索や CSV 出力があるが、実務では次のような場面ですぐに限界が来る。

  • 毎週の定例で「担当者別の未完了件数」「期限切れの課題」を同じ形式で出したい
  • 複数プロジェクトをまたいで、予定時間と実績時間を集計したい
  • 課題の一覧を Excel に貼り付け、別の管理表と突き合わせたい
  • コメントや添付ファイルまで含めてバックアップしておきたい

どれも「画面で検索 → CSV 出力 → Excel で加工」を手で繰り返せばできるが、毎回の手作業は抜け漏れの元になる。Backlog API を使えば、この一連の作業をスクリプト1本にまとめ、ボタン1つやタスクスケジューラで再実行できるようになる。

このシリーズは 情報の取得(読み取り) に絞る。課題の登録や更新も同じ API でできるが、取得だけなら誤操作でデータを壊す心配がなく、最初の一歩として安全だ。

Backlog API の基本構造

Backlog API(現行は v2)は、HTTPS で JSON を返す REST API だ。URL は次の形をしている。

URL の形
https://{スペースID}.backlog.com/api/v2/{リソース}
https://{スペースID}.backlog.jp/api/v2/{リソース}

例)https://example.backlog.com/api/v2/issues?projectId[]=12345&count=100
部分意味
スペースIDBacklog にログインするときの 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 と考えるとよい。

このシリーズの進め方

  1. 準備(PART 02〜04):APIキーの発行と接続確認、OAuth 2.0、全言語に共通する基本パターン
  2. 言語別(PART 05〜09):同じお題「指定プロジェクトの未完了課題を担当者別に一覧化する」を各言語で実装
  3. 実践(PART 10):複数プロジェクトの集計、予定と実績の比較、差分取得、定期レポート
  4. 付録(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 で自分のユーザー情報を取得して接続を確認する。キーを安全に保管する方法もあわせて扱う。

→ PART 02 — APIキーの発行と接続確認へ