Node.js と GAS の使い分け

JavaScript で Backlog API を使う場所は、大きく2つある。

Node.jsGoogle Apps Script(GAS)
動く場所手元の PC やサーバーGoogle のサーバー(PC の電源が切れていても動く)
公式 SDKbacklog-js が使える使えない。UrlFetchApp で直接呼ぶ
結果の出力先ファイル、データベース、他のシステムGoogle スプレッドシート、Google Chat、Gmail
定期実行タスクスケジューラや cron時間主導型トリガー(設定だけで済む)
制限特になし1回の実行は6分まで

社内システムとの連携やまとまったデータの取得は Node.js、「毎朝スプレッドシートを最新にしておきたい」なら GAS が手軽だ。

Node.js:環境を準備する

Node.js 20 以降(LTS 版)を前提にする。backlog-js は Node.js に標準で入っている fetch を使うので、追加のライブラリは不要だ。

PowerShell
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引数にクライアントを渡す書き方が基本になっている。

JavaScript(hello.mjs)
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})`);
PowerShell
node hello.mjs

以前からある new Backlog({ host, apiKey }) で作ったインスタンスにメソッドを生やす書き方(backlog.getIssues(...))も引き続き使える。インターネット上の多くのサンプルはこちらの書き方だ。

APIbacklog-js の関数
GET /users/myselfgetMyself(client)
GET /projects/{キー}getProject(client, key)
GET /projects/{キー}/statusesgetProjectStatuses(client, key)
GET /issuesgetIssues(client, params)
GET /issues/countgetIssuesCount(client, params)
GET /issues/{キー}/commentsgetIssueComments(client, key, params)
GET /rateLimitgetRateLimit(client)

パラメータは、API の projectId[] を projectId: [12345] のように [] を外した名前と配列 で渡す。SDK がクエリ文字列に展開してくれる。

エラーのときは、HTTP ステータスと Backlog のエラー本文を持った例外(BacklogApiError・BacklogAuthError など)が投げられる。err.status でステータス、err.body?.errors で errors 配列を取り出せる。429 の自動再試行はしない ので、必要なら自分で包む(次の例)。

Node.js:お題を実装する

JavaScript(open-issues.mjs)
// 指定プロジェクトの未完了課題を 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}`));
PowerShell
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 を繰り返す。

JavaScript
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 スプレッドシートに書き込み、毎朝自動で更新する。

  1. Google スプレッドシートを新しく作り、「拡張機能」→「Apps Script」 を開く
  2. 左の歯車アイコン 「プロジェクトの設定」 を開き、「スクリプト プロパティ」 に次の3つを追加する
    • BACKLOG_HOST:example.backlog.com
    • BACKLOG_API_KEY:APIキー
    • BACKLOG_PROJECT_KEY:DEV
  3. 同じ画面で、タイムゾーンが 「(GMT+09:00) 日本標準時」 になっていることを確認する

スクリプト プロパティに入れておけば、コードに APIキーを書かずに済む。ただし、そのスクリプトの編集権限を持つ人はプロパティを見られる ので、スプレッドシートの共有範囲には注意する。

GAS:スプレッドシートに取り込む

エディタの コード.gs を次の内容に置き換える。

Apps Script(コード.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:定期実行する

  1. Apps Script の左のメニューから 「トリガー」(時計のアイコン)を開く
  2. 「トリガーを追加」 をクリックする
  3. 実行する関数に 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 definedNode.js が古い。Node.js 20 以降に更新する
Object.groupBy is not a functionNode.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 で直接呼ぶ方法と比べる。

→ PART 09 — Javaで取得する(Backlog4j)へ