Backlog4j とは

Backlog4j は、Nulab が公開している Java 用の公式ライブラリ だ(MIT ライセンス)。API ごとにメソッドが用意されていて、レスポンスは Issue・Project などの型付きのオブジェクトで返る。2026年に入ってからも新しいバージョンが続けて公開されている。

項目内容
Maven 座標com.nulab-inc:backlog4j
この記事で使うバージョン2.11.0(執筆時点の最新)
必要な JavaJava 11 以降
依存Jackson(JSON の変換)。Gradle / Maven が自動で取り込む

既存の Java の業務システムやバッチに Backlog の情報を取り込みたいときに向いている。

プロジェクトを準備する

JDK 17 以降と Gradle を前提にする(Maven でも同じように書ける)。

ディレクトリ構成
backlog4j-fetch/
├─ build.gradle
├─ settings.gradle
└─ src/main/java/OpenIssues.java
settings.gradle
rootProject.name = 'backlog4j-fetch'
build.gradle
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> に次を追加する。

pom.xml(抜粋)
<dependency>
  <groupId>com.nulab-inc</groupId>
  <artifactId>backlog4j</artifactId>
  <version>2.11.0</version>
</dependency>

クライアントを作って呼んでみる

Backlog4j では、スペースのドメインに合わせた Configure クラス を選び、スペースIDと APIキーを渡してクライアントを作る。

スペースのドメインConfigure クラス
xxx.backlog.comBacklogComConfigure
xxx.backlog.jpBacklogJpConfigure
xxx.backlogtool.comBacklogToolConfigure

渡すのは ホスト名ではなくスペースID(example.backlog.com なら example)である点に注意する。

Java
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のリストを渡し、メソッドをつなげて条件を足していく。

Java
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)
parentChildparentChildType(GetIssuesParams.ParentChildType.NotChild) など
updatedSince・dueDateUntilupdatedSince("2026-11-01")・dueDateUntil("2026-11-30")
keywordkeyword("ログイン")

件数だけ知りたい場合は、同じ考え方の GetIssuesCountParams を backlog.getIssuesCount(...) に渡す。

お題を実装する

お題 の全体を1つのクラスにまとめる。ホスト名は BACKLOG_HOST から読み、ドメインに合わせて Configure クラスを選ぶ。

Java(src/main/java/OpenIssues.java)
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";
    }
}
PowerShell
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 を依存に追加する)。

Java
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 とエンコードして書く。

Backlog4jHttpClient+Jackson
書きやすさメソッドと型があり、IDE の補完が効くURL とパラメータ名を自分で書く
レスポンスIssue などの型付きオブジェクトJsonNode(null の扱いは path() で吸収できる)
ヘッダーレート制限のヘッダーは直接見られないすべて読める
新しい API への対応ライブラリの更新を待つすぐに呼べる
向いている場面課題・プロジェクトなど定番の API を業務システムで使う細かい制御が必要、依存を減らしたい

つまずきやすい点

症状原因と対処
認証エラー(401)になるConfigure にホスト名をまるごと渡している、またはドメインに合わない Configure クラスを使っている。スペースIDだけを渡す
UnsupportedClassVersionErrorJava 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 のクライアントを使い、複数プロジェクトの横断集計、予定と実績の比較、差分取得、定期レポートまでを実践する。

→ PART 10 — 実践:課題データの集計と定期レポートへ