この連載の共通のお題
PART 05〜09 では、言語ごとに次のお題を実装する。同じ処理を書き比べることで、言語ごとの違いがわかりやすくなる。
📋 お題:指定プロジェクトの未完了課題を担当者別に一覧化する
① プロジェクトキーからプロジェクトIDを調べる → ② 状態の一覧から「完了」以外の状態IDを集める → ③ 課題一覧を100件ずつすべて取得する → ④ 課題キー・件名・状態・担当者・期限日・予定/実績時間を CSV(または Excel)に出力する → ⑤ 担当者別の件数を表示する
この回では、①〜③で必要になる考え方を先に整理する。
ページネーション:100件ずつ取る
課題一覧(GET /api/v2/issues)は、count(1〜100、既定20)と offset(何件目から取るか)で範囲を指定する。全件取るには、offset を100ずつ増やしながら、返ってきた件数が count より少なくなるまで 繰り返す。
offset = 0
すべての課題 = []
繰り返す:
ページ = GET /api/v2/issues?…&count=100&offset={offset}&sort=created&order=asc
すべての課題 に ページ を追加
もし ページの件数 < 100 なら 終了
offset = offset + 100並び順を固定する
order を指定しないと降順(新しい順)になる。取得の途中で課題が追加・更新されると、ページの境目で 同じ課題が2回出たり、1件抜けたりする ことがある。全件取得では、途中で変わらない 登録日時の昇順(sort=created&order=asc)を指定しておくと、新しく登録された課題が最後に追加されるだけになり、ずれにくい。
それでも取得中に更新があると完全には防げないので、最後に課題IDで重複を除いておくと確実だ。
件数を先に数える
GET /api/v2/issues/count は、課題一覧と同じ絞り込み条件で 件数だけ を返す。何回呼ぶことになるかを先に知りたいとき、進捗を表示したいとき、件数だけの集計で十分なときに便利だ。
{ "count": 437 }minId / maxId で取る API
課題のコメント、プロジェクトの最近の活動、通知などは、offset ではなく ID を基準に 範囲を指定する。
| パラメータ | 意味 |
|---|---|
minId | この ID より大きいものを返す |
maxId | この ID より小さいものを返す |
count | 件数(1〜100、既定20) |
order | asc または desc(既定は desc) |
全件取るなら order=asc&count=100 で呼び、次は「前のページの最後の ID」を minId に渡して繰り返す。返ってきた件数が100未満になったら終わりだ。
min_id = なし
繰り返す:
ページ = GET /api/v2/issues/DEV-123/comments?count=100&order=asc[&minId={min_id}]
…
もし ページの件数 < 100 なら 終了
min_id = ページの最後の idこの方式は、前回取得した最後の ID を覚えておけば それ以降の新しいものだけ を取れるので、差分取得にも向いている。
配列パラメータの渡し方
名前の末尾に [] が付いたパラメータは、同じ名前を繰り返して複数の値を渡す。
/api/v2/issues?projectId[]=12345&statusId[]=1&statusId[]=2&statusId[]=3&count=100言語ごとの書き方は次のとおりだ。[ と ] を URL エンコードした %5B%5D で送っても同じ意味になる。
| 言語 | 書き方 | 注意 |
|---|---|---|
| curl | URL に直接書く | [] が範囲指定として解釈されるので -g(--globoff)を付ける |
| PowerShell | 文字列を組み立てる | -Body のハッシュテーブルでは同じキーを繰り返せない |
| Excel VBA | 文字列を組み立てる | 日本語のキーワードは WorksheetFunction.EncodeURL でエンコードする |
| Python(requests) | params={"statusId[]": [1, 2, 3]} | リストを渡すと自動で繰り返してくれる |
| JavaScript | URLSearchParams の append() を繰り返す | backlog-js なら statusId: [1, 2, 3] と配列で渡せる |
| Java(Backlog4j) | statusIds(List.of(1L, 2L)) | ライブラリが組み立ててくれる |
キーや名前を ID に変換する
課題一覧の絞り込みは、ほとんどが 数値の ID で指定する。人が覚えているのはプロジェクトキーや状態名なので、最初に変換用の API を呼ぶ。
| 知っているもの | 呼ぶ API | 使う値 |
|---|---|---|
プロジェクトキー(DEV) | GET /api/v2/projects/DEV | id → projectId[] |
| 状態名(処理中など) | GET /api/v2/projects/DEV/statuses | id → statusId[] |
| 担当者の名前 | GET /api/v2/projects/DEV/users | id → assigneeId[] |
| 種別(バグ・タスクなど) | GET /api/v2/projects/DEV/issueTypes | id → issueTypeId[] |
| カテゴリー | GET /api/v2/projects/DEV/categories | id → categoryId[] |
| マイルストーン・発生バージョン | GET /api/v2/projects/DEV/versions | id → milestoneId[]・versionId[] |
| 優先度 | GET /api/v2/priorities | id → priorityId[] |
状態の ID
既定の4つの状態は、どのプロジェクトでも同じ ID を持っている。
| ID | 状態 |
|---|---|
| 1 | 未対応 |
| 2 | 処理中 |
| 3 | 処理済み |
| 4 | 完了 |
プロジェクトで独自の状態(カスタム状態)を追加している場合、その ID は1〜4以外の、プロジェクトごとに異なる番号になる。「未完了」を statusId[]=1&statusId[]=2&statusId[]=3 と決め打ちすると、カスタム状態の課題が漏れる。この連載では 状態の一覧を取得し、「完了」(ID 4)以外をすべて集める 方法をとる。
変換用の API の結果はめったに変わらないので、1回の実行の中では最初に1回だけ呼び、結果を使い回す。
日付と null の扱い
絞り込みは日付単位
updatedSince・dueDateUntil などの日付の絞り込みは yyyy-MM-dd 形式で、時刻までは指定できない。「前回の実行以降に更新された課題」を取るときは、前回の日付をそのまま指定し、重複は課題IDで除く(PART 10)。
レスポンスの日時は UTC
created・updated は 2026-11-05T01:23:45Z のような UTC の日時だ。日本時間にするには9時間足す。一方、startDate・dueDate は時刻に意味がなく、2026-11-30T00:00:00Z のように日付だけが入っている。期限日を日本時間に変換すると日付が変わらないが、時刻付きで表示すると「09:00」になって紛らわしい ので、日付部分(先頭10文字)だけを使えばよい。
null になる項目
担当者が未設定の課題では assignee が null になる。dueDate・estimatedHours・actualHours なども、入力されていなければ null だ。issue.assignee.name のように書くと、担当者のいない課題で処理が止まる。各言語の回では、null のときに「(未割り当て)」などの値に置き換える書き方を示す。
レート制限への対処
すべてのレスポンスには、レート制限の状況を示すヘッダーが付く。
| ヘッダー | 内容 |
|---|---|
X-RateLimit-Limit | 1分間に受け付ける最大リクエスト数 |
X-RateLimit-Remaining | リセットまでに受け付ける残りのリクエスト数 |
X-RateLimit-Reset | カウントがリセットされる時刻(UNIX 時間) |
上限は「読み込み」「更新」「検索」「アイコン」の種別ごとに管理されていて、課題一覧・課題数・Wiki一覧・Wiki数の取得は「検索」 に数えられる。検索は読み込みより枠が小さいので、課題一覧を何百回も呼ぶ処理では特に注意する。現在の上限は GET /api/v2/rateLimit で種別ごとに確認できる。
公式ドキュメントで推奨されている対処は次のとおりだ。
- 1つのユーザーのリクエストは並列にせず、応答を受けてから次を送る
- 大量の検索・更新を行うときは、リクエストの間に1秒以上の間隔をあける
- 429 が返ったら、1分後(または
X-RateLimit-Resetの時刻)まで待って再送する - 定期実行では、過去の結果をキャッシュし、
updatedSinceなどで取得件数を絞る - 制限を避けるために複数ユーザーの APIキーを使い分けない
この連載のコードでは、429 を受けたら X-RateLimit-Reset まで待って再試行 し、X-RateLimit-Remaining が少なくなったら先回りして待つ形にする。
エラーレスポンスの読み方
エラーのときは 4xx・5xx のステータスとともに、次の形の JSON が返る。
{
"errors": [
{
"message": "No project.",
"code": 6,
"moreInfo": ""
}
]
}code の主な値と、スクリプトでの扱い方は次のとおりだ。全体は PART 11 にまとめている。
| code | 名前 | よくある原因 | 再試行 |
|---|---|---|---|
| 1 | InternalError | サーバー側の一時的な問題 | 少し待って再試行 |
| 5 | UnauthorizedOperationError | そのユーザーに権限がない操作 | しない |
| 6 | NoResourceError | プロジェクトキーや課題キーの間違い、参加していないプロジェクト | しない |
| 7 | InvalidRequestError | パラメータの誤り(count=500、日付の形式違いなど) | しない |
| 11 | AuthenticationError | APIキーの誤り、ドメイン違い | しない |
| 13 | TooManyRequestsError | レート制限を超えた(HTTP 429) | リセット後に再試行 |
再試行してよいのは 429 と 5xx だけ だ。401・404・400 は何度送っても結果が変わらないので、メッセージを表示して止める。
共通の処理の型
以上をまとめると、どの言語でも次の3つの関数を用意すれば、お題も PART 10 の実践もこなせる。
| 関数 | 役割 |
|---|---|
get(path, params) | 1回のリクエスト。APIキーのヘッダーを付け、429 と 5xx は待って再試行し、それ以外のエラーは errors[0].message を含めて例外にする |
get_all(path, params) | count=100 と offset で全件を取り、1つのリストにして返す |
| 変換用の関数 | プロジェクトキー → ID、状態一覧 → 未完了の状態IDのリスト |
次の PART 05 から、この型を各言語で書いていく。
✅ 次の記事では…
PART 05 では、まず curl と PowerShell でお題を実装する。追加のインストールなしで、Windows の標準機能だけで CSV まで出せる。