Node.js と GAS の使い分け
JavaScript で Backlog API を使う場所は、大きく2つある。
| Node.js | Google Apps Script(GAS) | |
|---|---|---|
| 動く場所 | 手元の PC やサーバー | Google のサーバー(PC の電源が切れていても動く) |
| 公式 SDK | backlog-js が使える | 使えない。UrlFetchApp で直接呼ぶ |
| 結果の出力先 | ファイル、データベース、他のシステム | Google スプレッドシート、Google Chat、Gmail |
| 定期実行 | タスクスケジューラや cron | 時間主導型トリガー(設定だけで済む) |
| 制限 | 特になし | 1回の実行は6分まで |
社内システムとの連携やまとまったデータの取得は Node.js、「毎朝スプレッドシートを最新にしておきたい」なら GAS が手軽だ。
Node.js:環境を準備する
Node.js 20 以降(LTS 版)を前提にする。backlog-js は Node.js に標準で入っている fetch を使うので、追加のライブラリは不要だ。
mkdir backlog-js-fetch; cd backlog-js-fetch
npm init -y
npm install backlog-jsこの回のコードは ES モジュール(import 文)で書くので、ファイルの拡張子を .mjs にする。
Node.js:backlog-js の基本
backlog-js は Nulab が公開している公式の SDK で、Backlog API の各エンドポイントに対応する関数がそろっている。現在のバージョンでは、createClient でクライアントを作り、使う関数だけを import して第1引数にクライアントを渡す書き方が基本になっている。
import { createClient, getMyself, getProject } from 'backlog-js';
const client = createClient({
host: process.env.BACKLOG_HOST, // 例: example.backlog.com
apiKey: process.env.BACKLOG_API_KEY, // OAuth 2.0 なら accessToken: '...'
});
const me = await getMyself(client);
const project = await getProject(client, process.env.BACKLOG_PROJECT_KEY);
console.log(`${me.name} / ${project.projectKey}(id=${project.id})`);node hello.mjs以前からある new Backlog({ host, apiKey }) で作ったインスタンスにメソッドを生やす書き方(backlog.getIssues(...))も引き続き使える。インターネット上の多くのサンプルはこちらの書き方だ。
| API | backlog-js の関数 |
|---|---|
GET /users/myself | getMyself(client) |
GET /projects/{キー} | getProject(client, key) |
GET /projects/{キー}/statuses | getProjectStatuses(client, key) |
GET /issues | getIssues(client, params) |
GET /issues/count | getIssuesCount(client, params) |
GET /issues/{キー}/comments | getIssueComments(client, key, params) |
GET /rateLimit | getRateLimit(client) |
パラメータは、API の projectId[] を projectId: [12345] のように [] を外した名前と配列 で渡す。SDK がクエリ文字列に展開してくれる。
エラーのときは、HTTP ステータスと Backlog のエラー本文を持った例外(BacklogApiError・BacklogAuthError など)が投げられる。err.status でステータス、err.body?.errors で errors 配列を取り出せる。429 の自動再試行はしない ので、必要なら自分で包む(次の例)。
Node.js:お題を実装する
// 指定プロジェクトの未完了課題を CSV に出力し、担当者別の件数を表示する
import { writeFile } from 'node:fs/promises';
import { setTimeout as sleep } from 'node:timers/promises';
import { createClient, getIssues, getIssuesCount, getProject, getProjectStatuses } from 'backlog-js';
const DONE_STATUS_ID = 4;
const PAGE_SIZE = 100;
const client = createClient({ host: process.env.BACKLOG_HOST, apiKey: process.env.BACKLOG_API_KEY });
// 429 と 5xx は待って再試行する
async function withRetry(fn, maxRetries = 5) {
for (let attempt = 1; ; attempt++) {
try {
return await fn();
} catch (err) {
const status = err?.status ?? 0;
const retryable = status === 429 || status >= 500;
if (!retryable || attempt >= maxRetries) {
const msg = err?.body?.errors?.[0]?.message ?? err.message;
throw new Error(`HTTP ${status}: ${msg}`);
}
const reset = Number(err.response?.headers?.get('X-RateLimit-Reset'));
const waitSec = status === 429 && reset ? Math.max(1, reset - Date.now() / 1000 + 1) : 5 * attempt;
console.warn(`HTTP ${status}: ${Math.round(waitSec)}秒待って再試行します(${attempt}回目)`);
await sleep(waitSec * 1000);
}
}
}
// count / offset で全件取得する
async function getAllIssues(params) {
const all = [];
for (let offset = 0; ; offset += PAGE_SIZE) {
const page = await withRetry(() => getIssues(client, { ...params, count: PAGE_SIZE, offset }));
all.push(...page);
if (page.length < PAGE_SIZE) return all;
}
}
const toJst = (iso) =>
iso ? new Date(iso).toLocaleString('ja-JP', { timeZone: 'Asia/Tokyo', hour12: false }) : '';
const csvCell = (v) => `"${String(v ?? '').replaceAll('"', '""')}"`;
const projectKey = process.argv[2] ?? process.env.BACKLOG_PROJECT_KEY;
const project = await withRetry(() => getProject(client, projectKey));
const statuses = await withRetry(() => getProjectStatuses(client, projectKey));
const params = {
projectId: [project.id],
statusId: statuses.filter((s) => s.id !== DONE_STATUS_ID).map((s) => s.id),
sort: 'created',
order: 'asc',
};
const { count } = await withRetry(() => getIssuesCount(client, params));
console.log(`対象: ${count} 件`);
const issues = [...new Map((await getAllIssues(params)).map((i) => [i.id, i])).values()];
const header = ['課題キー', '件名', '状態', '担当者', '期限日', '予定時間', '実績時間', '更新日時'];
const rows = issues.map((i) => [
i.issueKey, i.summary, i.status.name,
i.assignee?.name ?? '(未割り当て)',
i.dueDate?.slice(0, 10) ?? '',
i.estimatedHours ?? '', i.actualHours ?? '',
toJst(i.updated),
]);
const csv = '' + [header, ...rows].map((r) => r.map(csvCell).join(',')).join('\r\n');
const out = `issues_${projectKey}.csv`;
await writeFile(out, csv, 'utf8');
console.log(`出力: ${out}(${rows.length}件)`);
// 担当者別の件数
const byAssignee = Object.groupBy(rows, (r) => r[3]);
Object.entries(byAssignee)
.sort((a, b) => b[1].length - a[1].length)
.forEach(([name, list]) => console.log(`${String(list.length).padStart(4)} ${name}`));node open-issues.mjs DEVオプショナルチェーン(i.assignee?.name)と Null 合体演算子(?? '(未割り当て)')を使うと、担当者や期限日が null の課題を短く書ける。Object.groupBy は Node.js 21 以降で使える。Node.js 20 で動かす場合は、reduce で集計する書き方に置き換える。
💡 TypeScript で書く場合
backlog-js には型定義が含まれているので、TypeScript ではパラメータ名や戻り値の項目が補完される。sort と order は 'created' | 'updated' | … のような文字列リテラル型なので、いったん変数に入れたオブジェクトを渡すと string 型と推論されて型エラーになることがある。その場合はオブジェクトの末尾に as const を付けるか、引数に直接書く。
Node.js:SDK を使わずに fetch で書く
依存を増やしたくない場合や、SDK にまだない新しい API を呼ぶ場合は、標準の fetch で直接呼べる。配列パラメータは URLSearchParams の append を繰り返す。
async function backlogGet(path, params = {}) {
const qs = new URLSearchParams();
for (const [k, v] of Object.entries(params)) {
for (const x of [v].flat()) qs.append(k, x); // 配列なら同じキーで繰り返す
}
const url = `https://${process.env.BACKLOG_HOST}/api/v2/${path}?${qs}`;
const res = await fetch(url, { headers: { 'Backlog-API-Key': process.env.BACKLOG_API_KEY } });
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
console.log('残り', res.headers.get('X-RateLimit-Remaining'));
return res.json();
}
const issues = await backlogGet('issues', { 'projectId[]': [12345], 'statusId[]': [1, 2, 3], count: 100 });GAS:プロジェクトを準備する
GAS では、取得した課題を Google スプレッドシートに書き込み、毎朝自動で更新する。
- Google スプレッドシートを新しく作り、「拡張機能」→「Apps Script」 を開く
- 左の歯車アイコン 「プロジェクトの設定」 を開き、「スクリプト プロパティ」 に次の3つを追加する
BACKLOG_HOST:example.backlog.comBACKLOG_API_KEY:APIキーBACKLOG_PROJECT_KEY:DEV
- 同じ画面で、タイムゾーンが 「(GMT+09:00) 日本標準時」 になっていることを確認する
スクリプト プロパティに入れておけば、コードに APIキーを書かずに済む。ただし、そのスクリプトの編集権限を持つ人はプロパティを見られる ので、スプレッドシートの共有範囲には注意する。
GAS:スプレッドシートに取り込む
エディタの コード.gs を次の内容に置き換える。
const PROPS = PropertiesService.getScriptProperties();
const HOST = PROPS.getProperty('BACKLOG_HOST');
const API_KEY = PROPS.getProperty('BACKLOG_API_KEY');
const DONE_STATUS_ID = 4;
const PAGE_SIZE = 100;
/** 1回のリクエスト。429・5xx は待って再試行する */
function backlogGet_(path, params) {
const qs = Object.entries(params || {})
.flatMap(([k, v]) => [].concat(v).map((x) => `${encodeURIComponent(k)}=${encodeURIComponent(x)}`))
.join('&');
const url = `https://${HOST}/api/v2/${path}${qs ? '?' + qs : ''}`;
for (let attempt = 1; attempt <= 5; attempt++) {
const res = UrlFetchApp.fetch(url, {
headers: { 'Backlog-API-Key': API_KEY },
muteHttpExceptions: true, // エラーでも例外にせず、ステータスを見て判断する
});
const code = res.getResponseCode();
if (code === 200) return JSON.parse(res.getContentText('UTF-8'));
if (code === 429 || code >= 500) {
console.warn(`HTTP ${code}: 60秒待って再試行します(${attempt}回目)`);
Utilities.sleep(60 * 1000);
continue;
}
let msg = res.getContentText();
try { msg = JSON.parse(msg).errors[0].message; } catch (e) { /* そのまま */ }
throw new Error(`HTTP ${code}: ${msg}`);
}
throw new Error('再試行の上限に達しました');
}
/** count / offset で全件取得する */
function backlogGetAll_(path, params) {
const all = [];
for (let offset = 0; ; offset += PAGE_SIZE) {
const page = backlogGet_(path, { ...params, count: PAGE_SIZE, offset });
all.push(...page);
if (page.length < PAGE_SIZE) return all;
}
}
/** メイン:未完了課題を「課題一覧」シートに書き込む */
function fetchOpenIssues() {
const key = PROPS.getProperty('BACKLOG_PROJECT_KEY');
const project = backlogGet_(`projects/${key}`);
const statusIds = backlogGet_(`projects/${key}/statuses`)
.filter((s) => s.id !== DONE_STATUS_ID).map((s) => s.id);
const issues = backlogGetAll_('issues', {
'projectId[]': project.id, 'statusId[]': statusIds, sort: 'created', order: 'asc',
});
const header = ['課題キー', '件名', '状態', '担当者', '期限日', '予定時間', '実績時間', '更新日時'];
const rows = issues.map((i) => [
i.issueKey, i.summary, i.status.name,
i.assignee ? i.assignee.name : '(未割り当て)',
i.dueDate ? new Date(i.dueDate) : '', // シートのタイムゾーン(日本時間)で表示される
i.estimatedHours ?? '', i.actualHours ?? '',
new Date(i.updated),
]);
const ss = SpreadsheetApp.getActive();
const sheet = ss.getSheetByName('課題一覧') || ss.insertSheet('課題一覧');
sheet.clear();
const values = [header, ...rows];
sheet.getRange(1, 1, values.length, header.length).setValues(values); // 一度に書き込む
sheet.getRange(2, 5, Math.max(rows.length, 1), 1).setNumberFormat('yyyy/mm/dd');
sheet.getRange(2, 8, Math.max(rows.length, 1), 1).setNumberFormat('yyyy/mm/dd hh:mm');
sheet.getRange(1, 1, 1, header.length).setFontWeight('bold');
sheet.setFrozenRows(1);
sheet.getRange('J1').setValue(`最終更新: ${Utilities.formatDate(new Date(), 'Asia/Tokyo', 'yyyy/MM/dd HH:mm')}`);
console.log(`${rows.length} 件を書き込みました`);
}関数の一覧から fetchOpenIssues を選んで「実行」をクリックする。初回は権限の確認画面が出るので、自分のアカウントで許可する(外部サービスへの接続とスプレッドシートの編集を求められる)。
件名に = から始まるものがあると数式として解釈されるので、気になる場合は件名の列を setNumberFormat('@') で書式なしテキストにしてから書き込む。
GAS:定期実行する
- Apps Script の左のメニューから 「トリガー」(時計のアイコン)を開く
- 「トリガーを追加」 をクリックする
- 実行する関数に
fetchOpenIssues、イベントのソースに 「時間主導型」、種類に 「日付ベースのタイマー」、時刻に「午前7時〜8時」などを選んで保存する
これで毎朝、出社前にスプレッドシートが最新になる。Google Chat への通知と組み合わせる方法は、Google Chat Bot自動投稿 PART 04 で解説している。
⚠️ GAS の1回の実行は6分まで
課題が数千件あり、429 の待機が何度も入ると6分を超えて途中で止まることがある。対象を updatedSince で絞る、プロジェクトごとにトリガーを分ける、件数だけでよい集計は issues/count にする、といった工夫で回数を減らす。
つまずきやすい点
| 症状 | 原因と対処 |
|---|---|
Cannot use import statement outside a module | ファイルの拡張子が .js になっている。.mjs にするか、package.json に "type": "module" を追加する |
fetch is not defined | Node.js が古い。Node.js 20 以降に更新する |
Object.groupBy is not a function | Node.js 20 で実行している。21 以降にするか reduce で集計する |
古いサンプルの import 'isomorphic-fetch' でエラー | 現在の backlog-js は標準の fetch を使うので、その行は不要 |
| GAS で「Exception: 次の URL へのアクセスで HTTP 401」 | muteHttpExceptions を付けていない、または APIキーが違う。スクリプト プロパティの値を確認する |
| GAS の日時が9時間ずれる | スクリプトまたはスプレッドシートのタイムゾーンが日本になっていない |
✅ 次の記事では…
PART 09 では、公式の Java ライブラリ Backlog4j でお題を実装し、Java 標準の HttpClient で直接呼ぶ方法と比べる。