Backlog4j とは
Backlog4j は、Nulab が公開している Java 用の公式ライブラリ だ(MIT ライセンス)。API ごとにメソッドが用意されていて、レスポンスは Issue・Project などの型付きのオブジェクトで返る。2026年に入ってからも新しいバージョンが続けて公開されている。
| 項目 | 内容 |
|---|---|
| Maven 座標 | com.nulab-inc:backlog4j |
| この記事で使うバージョン | 2.11.0(執筆時点の最新) |
| 必要な Java | Java 11 以降 |
| 依存 | Jackson(JSON の変換)。Gradle / Maven が自動で取り込む |
既存の Java の業務システムやバッチに Backlog の情報を取り込みたいときに向いている。
プロジェクトを準備する
JDK 17 以降と Gradle を前提にする(Maven でも同じように書ける)。
backlog4j-fetch/
├─ build.gradle
├─ settings.gradle
└─ src/main/java/OpenIssues.javarootProject.name = 'backlog4j-fetch'plugins {
id 'application'
}
repositories {
mavenCentral()
}
dependencies {
implementation 'com.nulab-inc:backlog4j:2.11.0'
}
java {
toolchain { languageVersion = JavaLanguageVersion.of(17) }
}
application {
mainClass = 'OpenIssues'
}
tasks.withType(JavaCompile).configureEach { options.encoding = 'UTF-8' }
tasks.named('run') { standardOutput = System.out }Maven の場合は、pom.xml の <dependencies> に次を追加する。
<dependency>
<groupId>com.nulab-inc</groupId>
<artifactId>backlog4j</artifactId>
<version>2.11.0</version>
</dependency>クライアントを作って呼んでみる
Backlog4j では、スペースのドメインに合わせた Configure クラス を選び、スペースIDと APIキーを渡してクライアントを作る。
| スペースのドメイン | Configure クラス |
|---|---|
xxx.backlog.com | BacklogComConfigure |
xxx.backlog.jp | BacklogJpConfigure |
xxx.backlogtool.com | BacklogToolConfigure |
渡すのは ホスト名ではなくスペースID(example.backlog.com なら example)である点に注意する。
import com.nulabinc.backlog4j.BacklogClient;
import com.nulabinc.backlog4j.BacklogClientFactory;
import com.nulabinc.backlog4j.Project;
import com.nulabinc.backlog4j.User;
import com.nulabinc.backlog4j.conf.BacklogComConfigure;
import com.nulabinc.backlog4j.conf.BacklogConfigure;
BacklogConfigure conf = new BacklogComConfigure("example").apiKey(System.getenv("BACKLOG_API_KEY"));
BacklogClient backlog = new BacklogClientFactory(conf).newClient();
User me = backlog.getMyself();
Project project = backlog.getProject("DEV");
System.out.println(me.getName() + " / " + project.getProjectKey() + " (id=" + project.getId() + ")");OAuth 2.0(PART 03)で取得したトークンを使う場合は、apiKey(...) の代わりに accessToken(...) を設定する。
GetIssuesParams で絞り込む
課題一覧は backlog.getIssues(GetIssuesParams) で取得する。GetIssuesParams のコンストラクタにプロジェクトIDのリストを渡し、メソッドをつなげて条件を足していく。
GetIssuesParams params = new GetIssuesParams(List.of(project.getId()))
.statusIds(List.of(1, 2, 3)) // statusId[]
.sort(GetIssuesParams.SortKey.Created) // sort=created
.order(GetIssuesParams.Order.Asc) // order=asc
.count(100) // count
.offset(0); // offset
ResponseList<Issue> page = backlog.getIssues(params);| API のパラメータ | GetIssuesParams のメソッド |
|---|---|
statusId[] | statusIds(List)、既定の4状態なら statuses(List<Issue.StatusType>) |
assigneeId[] | assigneeIds(List) |
issueTypeId[]・categoryId[] | issueTypeIds(List)・categoryIds(List) |
milestoneId[] | milestoneIds(List) |
parentChild | parentChildType(GetIssuesParams.ParentChildType.NotChild) など |
updatedSince・dueDateUntil | updatedSince("2026-11-01")・dueDateUntil("2026-11-30") |
keyword | keyword("ログイン") |
件数だけ知りたい場合は、同じ考え方の GetIssuesCountParams を backlog.getIssuesCount(...) に渡す。
お題を実装する
お題 の全体を1つのクラスにまとめる。ホスト名は BACKLOG_HOST から読み、ドメインに合わせて Configure クラスを選ぶ。
import com.nulabinc.backlog4j.BacklogAPIException;
import com.nulabinc.backlog4j.BacklogClient;
import com.nulabinc.backlog4j.BacklogClientFactory;
import com.nulabinc.backlog4j.Issue;
import com.nulabinc.backlog4j.Project;
import com.nulabinc.backlog4j.ResponseList;
import com.nulabinc.backlog4j.api.option.GetIssuesParams;
import com.nulabinc.backlog4j.conf.BacklogComConfigure;
import com.nulabinc.backlog4j.conf.BacklogConfigure;
import com.nulabinc.backlog4j.conf.BacklogJpConfigure;
import com.nulabinc.backlog4j.conf.BacklogToolConfigure;
import java.io.BufferedWriter;
import java.math.BigDecimal;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.Date;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import java.util.function.Supplier;
import java.util.stream.Collectors;
/** 指定プロジェクトの未完了課題を CSV に出力し、担当者別の件数を表示する */
public class OpenIssues {
private static final long DONE_STATUS_ID = 4;
private static final int PAGE_SIZE = 100;
private static final ZoneId JST = ZoneId.of("Asia/Tokyo");
private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd");
private static final DateTimeFormatter DATETIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm");
public static void main(String[] args) throws Exception {
String host = System.getenv("BACKLOG_HOST"); // 例: example.backlog.com
String apiKey = System.getenv("BACKLOG_API_KEY");
String projectKey = args.length > 0 ? args[0] : System.getenv("BACKLOG_PROJECT_KEY");
BacklogClient backlog = new BacklogClientFactory(configure(host, apiKey)).newClient();
// ① プロジェクトID
Project project = withRetry(() -> backlog.getProject(projectKey));
// ② 「完了」以外の状態ID
List<Long> openStatusIds = withRetry(() -> backlog.getStatuses(projectKey)).stream()
.map(s -> (long) s.getId())
.filter(id -> id != DONE_STATUS_ID)
.collect(Collectors.toList());
// ③ 全件取得(count / offset)
Map<Long, Issue> issues = new LinkedHashMap<>(); // 課題IDで重複を除く
for (long offset = 0; ; offset += PAGE_SIZE) {
GetIssuesParams params = new GetIssuesParams(List.of(project.getId()))
.statusIds(openStatusIds)
.sort(GetIssuesParams.SortKey.Created)
.order(GetIssuesParams.Order.Asc)
.count(PAGE_SIZE)
.offset(offset);
ResponseList<Issue> page = withRetry(() -> backlog.getIssues(params));
page.forEach(i -> issues.put(i.getId(), i));
System.out.printf("offset=%d: %d件%n", offset, page.size());
if (page.size() < PAGE_SIZE) break;
}
// ④ CSV(Excel で開けるよう UTF-8 BOM 付き)
Path out = Path.of("issues_" + projectKey + ".csv");
try (BufferedWriter w = Files.newBufferedWriter(out, StandardCharsets.UTF_8)) {
w.write('');
w.write(csvLine(List.of("課題キー", "件名", "状態", "担当者", "期限日", "予定時間", "実績時間", "更新日時")));
for (Issue i : issues.values()) {
w.write(csvLine(List.of(
i.getIssueKey(), i.getSummary(), i.getStatus().getName(), assignee(i),
format(i.getDueDate(), DATE), num(i.getEstimatedHours()), num(i.getActualHours()),
format(i.getUpdated(), DATETIME))));
}
}
System.out.printf("出力: %s(%d件)%n", out, issues.size());
// ⑤ 担当者別の件数(多い順)
Map<String, Long> byAssignee = issues.values().stream()
.collect(Collectors.groupingBy(OpenIssues::assignee, TreeMap::new, Collectors.counting()));
byAssignee.entrySet().stream()
.sorted(Map.Entry.<String, Long>comparingByValue().reversed())
.forEach(e -> System.out.printf("%4d %s%n", e.getValue(), e.getKey()));
}
/** ホスト名のドメインに合わせて Configure を選ぶ(渡すのはスペースID) */
static BacklogConfigure configure(String host, String apiKey) {
String spaceId = host.substring(0, host.indexOf('.'));
if (host.endsWith(".backlog.jp")) return new BacklogJpConfigure(spaceId).apiKey(apiKey);
if (host.endsWith(".backlogtool.com")) return new BacklogToolConfigure(spaceId).apiKey(apiKey);
return new BacklogComConfigure(spaceId).apiKey(apiKey);
}
/** 429 と 5xx は待って再試行する */
static <T> T withRetry(Supplier<T> call) throws InterruptedException {
for (int attempt = 1; ; attempt++) {
try {
return call.get();
} catch (BacklogAPIException e) {
int status = e.getStatusCode();
boolean retryable = status == 429 || status >= 500;
if (!retryable || attempt >= 5) throw e;
long waitSec = status == 429 ? 60 : 5L * attempt;
System.err.printf("HTTP %d: %d秒待って再試行します(%d回目)%n", status, waitSec, attempt);
Thread.sleep(waitSec * 1000);
}
}
}
static String assignee(Issue i) {
return i.getAssignee() != null ? i.getAssignee().getName() : "(未割り当て)";
}
static String format(Date d, DateTimeFormatter f) {
return d == null ? "" : d.toInstant().atZone(JST).format(f); // UTC → 日本時間
}
static String num(BigDecimal v) {
return v == null ? "" : v.stripTrailingZeros().toPlainString();
}
static String csvLine(List<String> cells) {
List<String> quoted = new ArrayList<>();
for (String c : cells) quoted.add("\"" + (c == null ? "" : c.replace("\"", "\"\"")) + "\"");
return String.join(",", quoted) + "\r\n";
}
}gradle run --args="DEV"offset=0: 100件
offset=100: 100件
offset=200: 37件
出力: issues_DEV.csv(237件)
64 佐藤 花子
51 山田 太郎
48 鈴木 一郎
41 (未割り当て)
33 高橋 次郎Backlog4j は日時を java.util.Date で返すので、toInstant().atZone(JST) で日本時間に変換してから整形している。期限日も同じ方法で変換すると、日付は変わらずに正しく表示される。予定時間・実績時間は BigDecimal で、未入力なら null になる。
💡 ラムダ式の中の変数
withRetry(() -> backlog.getIssues(params)) のように、ラムダ式で使う変数は実質的に final である必要がある。ループの中で毎回 params を新しく作っているのはこのためだ。
エラーと再試行
Backlog4j は、API がエラーを返すと BacklogAPIException(非検査例外)を投げる。
| メソッド | 内容 |
|---|---|
getStatusCode() | HTTP ステータス(429、404 など) |
getBacklogAPIError().getErrors() | Backlog の errors 配列。各要素の getCode()・getMessage() で内容を見る |
getMessage() | ステータスとエラー内容をまとめた文字列。429 のときは、いつから再び使えるかも含まれる |
Backlog4j は 429 を自動では再試行しないため、上の withRetry で包んでいる。429 のときは公式ドキュメントの推奨どおり1分待つ。リセット時刻まで細かく待ちたい場合は、次の HttpClient の方法でヘッダーを直接読む。
HttpClient で直接呼ぶ方法との比較
Java 11 以降に標準で入っている java.net.http.HttpClient でも呼べる。JSON の解析には、Backlog4j と一緒に取り込まれる Jackson を使う(Backlog4j を使わない場合は com.fasterxml.jackson.core:jackson-databind を依存に追加する)。
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
HttpClient http = HttpClient.newHttpClient();
ObjectMapper mapper = new ObjectMapper();
String url = "https://" + System.getenv("BACKLOG_HOST") + "/api/v2/issues"
+ "?projectId%5B%5D=12345&statusId%5B%5D=1&statusId%5B%5D=2&count=100&offset=0";
HttpRequest req = HttpRequest.newBuilder(URI.create(url))
.header("Backlog-API-Key", System.getenv("BACKLOG_API_KEY"))
.GET().build();
HttpResponse<String> res = http.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println("残り: " + res.headers().firstValue("X-RateLimit-Remaining").orElse("?"));
for (JsonNode issue : mapper.readTree(res.body())) {
String assignee = issue.path("assignee").path("name").asText("(未割り当て)");
System.out.println(issue.get("issueKey").asText() + " " + assignee + " " + issue.get("summary").asText());
}URI.create は [ と ] を受け付けないため、%5B%5D とエンコードして書く。
| Backlog4j | HttpClient+Jackson | |
|---|---|---|
| 書きやすさ | メソッドと型があり、IDE の補完が効く | URL とパラメータ名を自分で書く |
| レスポンス | Issue などの型付きオブジェクト | JsonNode(null の扱いは path() で吸収できる) |
| ヘッダー | レート制限のヘッダーは直接見られない | すべて読める |
| 新しい API への対応 | ライブラリの更新を待つ | すぐに呼べる |
| 向いている場面 | 課題・プロジェクトなど定番の API を業務システムで使う | 細かい制御が必要、依存を減らしたい |
つまずきやすい点
| 症状 | 原因と対処 |
|---|---|
| 認証エラー(401)になる | Configure にホスト名をまるごと渡している、またはドメインに合わない Configure クラスを使っている。スペースIDだけを渡す |
UnsupportedClassVersionError | Java 8 で実行している。Java 11 以降(できれば 17 以降)を使う |
| コンソールの日本語が化ける | Windows のコンソールの文字コード。PowerShell で [Console]::OutputEncoding = [Text.Encoding]::UTF8 を実行するか、Java に -Dstdout.encoding=UTF-8 を渡す |
| ソースのコンパイルで文字化け・エラー | ソースの文字コード指定がない。build.gradle に options.encoding = 'UTF-8' を入れる |
| カスタム状態の課題が出てこない | statuses(...) で既定の状態だけを指定している。getStatuses(projectKey) の結果から ID を集めて statusIds(...) に渡す |
✅ 次の記事では…
PART 10 では Python のクライアントを使い、複数プロジェクトの横断集計、予定と実績の比較、差分取得、定期レポートまでを実践する。