取得できる主な情報の一覧
Backlog API v2 の取得(GET)系の主な API を分類した。パスはすべて https://{ホスト}/api/v2/ に続く部分で、{キー} はプロジェクトのキーまたは ID、{課題} は課題キー(DEV-123)または課題 ID を表す。網羅的な一覧は公式ドキュメントを参照してほしい。
スペース・ユーザー
| 情報 | パス | 補足 |
|---|---|---|
| スペース情報 | space | スペース名、タイムゾーンなど |
| スペースの最近の更新 | space/activities | minId/maxId で取得 |
| スペースの容量の使用状況 | space/diskUsage | 管理者のみ |
| 認証ユーザー(自分) | users/myself | 接続確認に使う |
| ユーザー一覧 | users | スペースの全ユーザー |
| ユーザーの最近の活動 | users/{ユーザーID}/activities | 数値のユーザーID |
| チーム一覧 | teams | |
| レート制限の状況 | rateLimit | 種別ごとの上限・残り・リセット時刻 |
| ライセンス(プラン) | space/licence | 使える機能の確認 |
プロジェクトと設定値
| 情報 | パス | 補足 |
|---|---|---|
| プロジェクト一覧 | projects | archived・all(管理者)で範囲を指定 |
| プロジェクト情報 | projects/{キー} | キー → ID の変換に使う |
| 状態一覧 | projects/{キー}/statuses | カスタム状態を含む |
| 種別一覧 | projects/{キー}/issueTypes | バグ・タスクなど |
| カテゴリー一覧 | projects/{キー}/categories | |
| マイルストーン・発生バージョン | projects/{キー}/versions | 同じ一覧で両方に使う |
| カスタム属性一覧 | projects/{キー}/customFields | ID は customField_{ID} の絞り込みに使う |
| プロジェクトメンバー | projects/{キー}/users | 担当者の ID を調べる |
| プロジェクトの最近の活動 | projects/{キー}/activities | minId/maxId で取得 |
| 優先度一覧 | priorities | スペース共通 |
| 完了理由一覧 | resolutions | スペース共通 |
課題
| 情報 | パス | 補足 |
|---|---|---|
| 課題一覧 | issues | count(最大100)/offset。レート制限は「検索」 |
| 課題数 | issues/count | 一覧と同じ絞り込みで件数だけ |
| 課題の詳細 | issues/{課題} | 説明(description)を含む |
| コメント一覧 | issues/{課題}/comments | minId/maxId。変更履歴は changeLog |
| コメント数 | issues/{課題}/comments/count | |
| 添付ファイル一覧 | issues/{課題}/attachments | |
| 添付ファイルのダウンロード | issues/{課題}/attachments/{添付ID} | ファイル名は Content-Disposition |
| 関連する共有ファイル | issues/{課題}/sharedFiles | |
| 課題の参加者 | issues/{課題}/participants |
Wiki・ドキュメント・ファイル
| 情報 | パス | 補足 |
|---|---|---|
| Wiki ページ一覧 | wikis?projectIdOrKey={キー} | 本文は含まない。レート制限は「検索」 |
| Wiki ページ数 | wikis/count?projectIdOrKey={キー} | |
| Wiki ページ(本文) | wikis/{WikiID} | content に本文 |
| Wiki の履歴・タグ・添付 | wikis/{WikiID}/history、wikis/tags?projectIdOrKey={キー}、wikis/{WikiID}/attachments | |
| ドキュメント一覧・ツリー | documents、documents/tree | ドキュメント機能を使っているプロジェクト |
| 共有ファイル一覧 | projects/{キー}/files/metadata/{フォルダのパス} | ルートは files/metadata/ |
| 共有ファイルのダウンロード | projects/{キー}/files/{ファイルID} |
Git・プルリクエスト・通知
| 情報 | パス | 補足 |
|---|---|---|
| Git リポジトリ一覧 | projects/{キー}/git/repositories | |
| プルリクエスト一覧 | projects/{キー}/git/repositories/{リポジトリ名}/pullRequests | statusId[] で状態を絞り込む |
| プルリクエスト数 | …/pullRequests/count | |
| プルリクエストのコメント | …/pullRequests/{番号}/comments | minId/maxId |
| 自分宛ての通知 | notifications | minId/maxId |
| ウォッチ一覧 | users/{ユーザーID}/watchings | |
| 最近見た課題・Wiki | users/myself/recentlyViewedIssues、…/recentlyViewedWikis |
やりたいこと別の逆引き
| やりたいこと | 方法 | 関連する回 |
|---|---|---|
| APIキーが正しいか確かめたい | users/myself を呼ぶ | PART 02 |
| プロジェクトキーから ID を知りたい | projects/{キー} の id | PART 04 |
| 未完了の課題をすべて取りたい | 状態一覧から ID 4(完了)以外を集め、statusId[] に渡してページネーション | PART 04、PART 05〜09 |
| 自分が担当の課題だけ | assigneeId[]={users/myself の id} | PART 05 |
| 担当者が未設定の課題 | API に「未設定」の条件はないので、取得後に assignee が null のものを選ぶ | PART 04 |
| 期限切れの課題 | 未完了の状態 + dueDateUntil={昨日} | PART 10 |
| 期限日が未入力の課題 | hasDueDate=false | |
| 件数だけ知りたい | issues/count(一覧より軽い) | PART 07 |
| 前回以降に更新された課題だけ | updatedSince={前回の日付-1日} + 課題IDで上書き | PART 10 |
| 課題が完了になった日時 | コメント一覧の changeLog で field が status の変更を探す | PART 07 |
| 予定時間と実績時間の比較 | estimatedHours・actualHours を集計 | PART 10 |
| 親課題だけ・子課題だけ | parentChild(1:子課題以外、2:子課題 など) | 下記 |
| カスタム属性で絞り込みたい | customFields で ID を調べ、customField_{ID} などを付ける | 下記 |
| 添付ファイルをまとめて保存 | 添付ファイル一覧 → 1件ずつダウンロード | PART 07 |
| Wiki をバックアップしたい | Wiki 一覧で ID を集め、wikis/{ID} で本文を1件ずつ取得 | |
| マージ待ちのプルリクエスト | pullRequests?statusId[]=1(1:Open) | |
| Excel のシートに取り込みたい | VBA(WinHttp+VBA-JSON) | PART 06 |
| スプレッドシートに毎朝取り込みたい | GAS+時間主導型トリガー | PART 08 |
| 利用者ごとの権限で動くツールを作りたい | OAuth 2.0 | PART 03 |
課題一覧のよく使う絞り込み
| パラメータ | 内容 | 例 |
|---|---|---|
projectId[] | プロジェクト ID(複数可) | projectId[]=12345&projectId[]=67890 |
statusId[] | 状態 ID(1 未対応、2 処理中、3 処理済み、4 完了、カスタム状態) | statusId[]=1&statusId[]=2 |
assigneeId[] | 担当者のユーザー ID | assigneeId[]=1073741824 |
issueTypeId[]・categoryId[]・milestoneId[] | 種別・カテゴリー・マイルストーン | |
priorityId[] | 優先度(priorities で確認) | |
parentChild | 0:すべて、1:子課題以外、2:子課題、3:親課題でも子課題でもない、4:親課題(新しい値も追加されている) | parentChild=1 |
keyword | キーワード(URL エンコードする) | keyword=%E3%83%AD%E3%82%B0%E3%82%A4%E3%83%B3 |
createdSince/Until | 登録日の範囲(yyyy-MM-dd) | createdSince=2026-10-01 |
updatedSince/Until | 更新日の範囲 | updatedSince=2026-11-01 |
dueDateSince/Until | 期限日の範囲 | dueDateUntil=2026-11-04 |
hasDueDate | false で期限日なしの課題(true は指定できない) | hasDueDate=false |
attachment | true で添付ファイルのある課題 | attachment=true |
sort・order | 並び順。全件取得では created・asc で固定する | sort=created&order=asc |
count・offset | 件数(1〜100、既定20)と開始位置 | count=100&offset=200 |
customField_{ID} | テキスト型のカスタム属性のキーワード。数値・日付型は _min/_max、リスト型は customField_{ID}[] | customField_123_min=10 |
言語別の書き方早見表
| 処理 | curl / PowerShell | Excel VBA | Python | JavaScript | Java(Backlog4j) |
|---|---|---|---|---|---|
| APIキー | -H "Backlog-API-Key: …" / -Headers @{…} | SetRequestHeader "Backlog-API-Key", … | session.headers["Backlog-API-Key"] | createClient({ host, apiKey }) | new BacklogComConfigure(id).apiKey(…) |
| 配列パラメータ | URL に直接(curl は -g) | 文字列を連結 | {"statusId[]": [1, 2]} | statusId: [1, 2] | .statusIds(List.of(1L, 2L)) |
| JSON の解析 | jq / ConvertFrom-Json | VBA-JSON の ParseJson | resp.json() | SDK が変換 | SDK が型に変換 |
| null の扱い | // "既定値" / if ($x) {…} | IsNull・IsObject | (i.get("assignee") or {}) | i.assignee?.name ?? '…' | != null |
| ヘッダーの参照 | -w / $res.Headers[…] | GetResponseHeader | resp.headers.get(…) | err.response.headers.get(…) | 直接は不可(HttpClient を使う) |
| UTC → 日本時間 | ConvertTo-Jst(PART 05) | IsoToJst(PART 06) | tz_convert("Asia/Tokyo") | toLocaleString(…, { timeZone }) | atZone(ZoneId.of("Asia/Tokyo")) |
| Excel で開ける CSV | -Encoding utf8BOM(7) | (シートに直接書く) | encoding="utf-8-sig" | 先頭に '' | 先頭に '' |
| 解説 | PART 05 | PART 06 | PART 07 | PART 08 | PART 09 |
エラーコードと対処
エラーの本文 {"errors":[{"message": …, "code": …, "moreInfo": …}]} の code の意味と対処をまとめる。
| code | 名前 | 意味 | 対処 |
|---|---|---|---|
| 1 | InternalError | サーバー側の不具合など | 少し待って再試行。続くようなら Backlog の障害情報を確認する |
| 2 | LicenceError | 今のプランでは使えない機能 | プランの機能を確認する |
| 3 | LicenceExpiredError | ライセンスの期限切れ | スペースの管理者に確認する |
| 4 | AccessDeniedError | IP アドレス制限などで拒否された | 接続元の IP が許可されているか管理者に確認する |
| 5 | UnauthorizedOperationError | そのユーザーに権限のない操作 | キーを発行したユーザーの権限を確認する |
| 6 | NoResourceError | 対象が存在しない | プロジェクトキー・課題キー・ID の間違い、参加していないプロジェクト |
| 7 | InvalidRequestError | パラメータが不正 | count の範囲、日付の形式(yyyy-MM-dd)、[] の付け忘れを確認する |
| 8 | SpaceOverCapacityError | スペースの容量の上限を超える | 取得では通常起きない |
| 9 | ResourceOverflowError | 追加できる数の上限を超える | 取得では通常起きない |
| 10 | TooLargeFileError | ファイルが大きすぎる | 取得では通常起きない |
| 11 | AuthenticationError | 認証に失敗した | APIキーの誤り、ドメイン(.com/.jp)の違い |
| 12 | RequiredMFAError | 2段階認証が必須のスペースで、ユーザーが2段階認証を有効にしていない | キーを発行したユーザーの2段階認証を有効にする |
| 13 | TooManyRequestsError | レート制限を超えた | X-RateLimit-Reset まで(または1分)待って再試行。並列実行をやめる |
HTTP ステータス別の対処
| ステータス | よくある原因 | 再試行 |
|---|---|---|
| 400 | パラメータの誤り(code 7) | しない |
| 401 | APIキーの誤り、OAuth 2.0 のトークン切れ(詳細は WWW-Authenticate ヘッダー) | トークン切れなら更新してから1回だけ |
| 403 | 権限不足、IP アドレス制限 | しない |
| 404 | キーや ID の誤り、参加していないプロジェクト | しない |
| 429 | レート制限(code 13) | リセット時刻まで待って再試行 |
| 5xx | サーバー側の一時的な問題 | 待ち時間を延ばしながら数回 |
シリーズのまとめ
11回にわたり、Backlog API での情報取得を、APIキーの発行から5つの言語での実装、定期レポートまで扱った。最後に要点を振り返る。
- APIキーはヘッダー
Backlog-API-Keyで渡し、コードやブックに直接書かない(PART 02) - 利用者ごとの権限で動くツールには OAuth 2.0 を使う(PART 03)
- 一覧は最大100件。
count/offsetまたはminIdでページネーションする(PART 04) - 状態などは ID で絞り込む。カスタム状態があるので「未完了」は状態一覧から作る
- 429 は待って再試行し、定期実行では
updatedSinceとキャッシュで回数を減らす(PART 10) - 日時は UTC。期限日は日付だけを使う
AWS のリソースや料金を同じように取得する方法は、boto3 シリーズ で解説している。取得した結果をチャットに流すなら、Google Chat Bot自動投稿シリーズ も参考にしてほしい。