この連載の共通のお題

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)
orderasc または 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 で送っても同じ意味になる。

言語書き方注意
curlURL に直接書く[] が範囲指定として解釈されるので -g(--globoff)を付ける
PowerShell文字列を組み立てる-Body のハッシュテーブルでは同じキーを繰り返せない
Excel VBA文字列を組み立てる日本語のキーワードは WorksheetFunction.EncodeURL でエンコードする
Python(requests)params={"statusId[]": [1, 2, 3]}リストを渡すと自動で繰り返してくれる
JavaScriptURLSearchParams の append() を繰り返すbacklog-js なら statusId: [1, 2, 3] と配列で渡せる
Java(Backlog4j)statusIds(List.of(1L, 2L))ライブラリが組み立ててくれる

キーや名前を ID に変換する

課題一覧の絞り込みは、ほとんどが 数値の ID で指定する。人が覚えているのはプロジェクトキーや状態名なので、最初に変換用の API を呼ぶ。

知っているもの呼ぶ API使う値
プロジェクトキー(DEV)GET /api/v2/projects/DEVid → projectId[]
状態名(処理中など)GET /api/v2/projects/DEV/statusesid → statusId[]
担当者の名前GET /api/v2/projects/DEV/usersid → assigneeId[]
種別(バグ・タスクなど)GET /api/v2/projects/DEV/issueTypesid → issueTypeId[]
カテゴリーGET /api/v2/projects/DEV/categoriesid → categoryId[]
マイルストーン・発生バージョンGET /api/v2/projects/DEV/versionsid → milestoneId[]・versionId[]
優先度GET /api/v2/prioritiesid → 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-Limit1分間に受け付ける最大リクエスト数
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 が返る。

レスポンス例(404)
{
  "errors": [
    {
      "message": "No project.",
      "code": 6,
      "moreInfo": ""
    }
  ]
}

code の主な値と、スクリプトでの扱い方は次のとおりだ。全体は PART 11 にまとめている。

code名前よくある原因再試行
1InternalErrorサーバー側の一時的な問題少し待って再試行
5UnauthorizedOperationErrorそのユーザーに権限がない操作しない
6NoResourceErrorプロジェクトキーや課題キーの間違い、参加していないプロジェクトしない
7InvalidRequestErrorパラメータの誤り(count=500、日付の形式違いなど)しない
11AuthenticationErrorAPIキーの誤り、ドメイン違いしない
13TooManyRequestsErrorレート制限を超えた(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 まで出せる。

→ PART 05 — curl・PowerShellで取得するへ