Cloudflare Workersで外部APIと連携する際、認証トークンの管理方法・エラーハンドリングの粒度・レート制限への対応——こうした実装の詳細が、プロダクション環境での安定性と性能を大きく左右します。本記事では、Workers環境変数を活用したAPI連携の実装パターンを、よくある失敗事例とともに解説します。
地方中小企業のシステム担当者からは「freeeやジョブカン、Chatworkなど複数のAPIを連携させたいが、認証情報をツール側に直接入力するのは怖い」「API連携のコード実装で、エラーハンドリングをどこまで書けばいいのかわからない」といった相談が多く寄せられています。Cloudflare Workersを使えば、環境変数管理とリトライロジックにより、認証情報流出のリスクを最小化しつつ、本番環境での安定性を確保できます。
API認証の3つのパターン——セキュリティリスクの正しい理解が実装の出発点
API連携の成否を左右するのは、認証情報をどのように管理し、Workersコードに安全に渡すかという設計判断です。最も危険なのは、APIのIDやパスワードをコード内にハードコーディングすること。freeeやジョブカン、Chatworkといったクラウドシステムの認証情報がコード内に埋め込まれた場合、流出時は自社の財務データや従業員情報が丸ごと盗まれます。
セキュリティが高い順に整理すると、OAuth 2.0フロー（外部サービスがユーザーに代わってトークンを発行する仕組み）> APIキー＋環境変数管理 > 直接入力・ハードコーディングとなります。
// ❌ 絶対に避けるべき実装
const PASSWORD = "super-secret-password"; // コードに埋め込みは厳禁
// ✅ 正しい実装：環境変数を使用
const API_KEY = env.EXTERNAL_API_KEY; // 環境変数から取得
const API_SECRET = env.EXTERNAL_API_SECRET;
// OAuth 2.0トークンの場合
const accessToken = await getOAuth2Token(env.CLIENT_ID, env.CLIENT_SECRET);
環境変数はコード内に平文が残らず、Cloudflareダッシュボードの「環境変数」セクションで設定することで安全に管理できます。このアプローチにより、認証情報の一元管理と定期的なローテーション（交換）が容易になります。
京谷商会では、複数のクライアント企業のfreee・Salesforce連携を実装する際、すべてのプロジェクトで環境変数方式を採用しており、導入から3年間で認証情報流出による障害はゼロです。テクノロジードメイン統括では、本番環境（Production）と開発環境（Preview）で環境変数を分離設定する運用ルールを定めており、誤った環境で本番データを上書きするリスクも防止しています。
認証エラー・タイムアウト・レート制限——実装で最もよく発生する3つの失敗
API連携のコード実装で最もよく起きるトラブルは、①OAuth 2.0トークンの有効期限切れに気付かず古いキャッシュが配信される、②外部APIの遅延によるタイムアウトで処理が中断される、③レート制限に達して呼び出しが失敗することです。重要なのは、エラーに気付かないまま処理が部分的に失敗しているケースが大多数である点です。
トークン期限切れで「成功」と見なされるバグ
OAuth 2.0でよく起きる失敗は、アクセストークンの有効期限が切れたにもかかわらず、コード上では「APIリクエスト自体は成功」と判定される事例です。freeeの給与明細取得APIはトークン期限切れの場合HTTP 401レスポンスを返しますが、初心者の実装ではステータスコード200〜299のみが「成功」と判定され、401エラーが静かに無視されて古いキャッシュデータが配信され続ける事態が発生します。
// ❌ 悪い実装：エラーを見逃す
async function getFreeeData(accessToken) {
const response = await fetch('https://api.freee.co.jp/api/1/companies', {
headers: { 'Authorization': `Bearer ${accessToken}` }
});
const data = await response.json();
return data; // 401でもJSONが返るため、data.errorに気付かない
}
// ✅ 正しい実装：ステータスコードとレスポンス本体の両方をチェック
async function getFreeeData(accessToken) {
const response = await fetch('https://api.freee.co.jp/api/1/companies', {
headers: { 'Authorization': `Bearer ${accessToken}` }
});
if (!response.ok) {
if (response.status === 401) {
// トークン期限切れ：新しいトークンを取得してリトライ
const newToken = await refreshOAuth2Token(env.REFRESH_TOKEN);
return getFreeeData(newToken);
}
throw new Error(`API error: ${response.status} ${response.statusText}`);
}
const data = await response.json();
if (data.error) {
throw new Error(`Freee API error: ${data.error}`);
}
return data;
}
このパターンは特に給与計算システム（ジョブカン）やSalesforce連携で多発しており、見積もりデータが古いまま営業に渡されるという事例に発展することもあります。したがって、OAuth 2.0トークン利用時は必ずHTTPステータスコードをチェックし、401エラーが返ったら新トークンを取得してリトライすることが必須です。
タイムアウト直前の「部分的な状態」がデータベースに残る
Cloudflare Workersのリクエストタイムアウトは約30秒です。外部APIのレスポンスが遅い場合（Salesforceレポート取得など）、タイムアウトで処理が中断されエラーメッセージなしにユーザーに返却されます。特に危険なのは、タイムアウト直前の「部分的な状態」です。100件の受発注データをループで処理中に50件目でタイムアウトした場合、データベースには50件だけ登録され、後の50件が欠落したままになります。
// ✅ 正しい実装：指数バックオフでリトライ
async function fetchWithRetry(url, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 10000); // 10秒
const response = await fetch(url, { signal: controller.signal });
clearTimeout(timeoutId);
if (response.ok) return response.json();
if (response.status >= 500) {
// サーバーエラーはリトライ対象
await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
continue;
}
throw new Error(`HTTP ${response.status}`);
} catch (error) {
if (i === maxRetries - 1) throw error;
await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
}
}
}
指数バックオフとは、リトライするたびに待機時間を倍増させる手法です。1秒 → 2秒 → 4秒と待つことで、相手サーバーの負荷が下がるのを待ちながら自動復旧を試みます。この実装により、タイムアウトで処理が中断されるのではなく、接続回復のチャンスが3回生まれます。
HTTP 429レート制限への対応がない場合の連鎖失敗
freee、Chatwork、LINE Messaging APIなど、ほぼすべてのクラウドAPIにはレート制限があります。「1分間に60リクエストまで」といった上限に達するとHTTP 429レスポンスが返されます。毎月末に全従業員の給与データをfreeeから取得するBatch処理を実装した場合、データが多いと簡単にレート制限に引っかかります。
// ✅ レート制限対応：429レスポンスを読んでスリープ
async function fetchAllEmployeesWithRateLimit() {
const employees = [];
for (let page = 1; page <= 100; page++) {
const response = await fetch(`/api/employees?page=${page}`);
if (response.status === 429) {
// Rate-Limit-Reset ヘッダを確認
const resetTime = parseInt(response.headers.get('X-Rate-Limit-Reset') || '60');
console.log(`Rate limited. Waiting ${resetTime}ms`);
await new Promise(r => setTimeout(r, resetTime));
page--; // 同じページを再試行
continue;
}
const data = await response.json();
employees.push(...data);
}
return employees;
}
APIレスポンスヘッダのX-Rate-Limit-ResetやRetry-Afterを読むことで、「あと何秒待てば再試行できるか」を知ることができます。この情報から無駄な待機時間を削減でき、結果としてBatch処理全体の所要時間が予測可能になります。
エラーコンテキスト付きロギング——本番環境での障害検知を実現する
API連携のコードが本番で動く際、最も大切なのは「何が起きたのか、後から追跡できるようにすること」です。エラーハンドリングは単に例外をcatchするだけでなく、何がエラーの原因で、どの外部APIが関わったのか、タイムスタンプは何かを記録する必要があります。
// ✅ 本番環境に耐える実装：エラーコンテキスト付きロギング
async function callExternalAPI(apiName, endpoint, options) {
const startTime = Date.now();
const requestId = crypto.randomUUID(); // 各リクエストに一意のID
try {
const response = await fetch(endpoint, options);
const duration = Date.now() - startTime;
if (!response.ok) {
console.error({
level: 'error',
api: apiName,
status: response.status,
duration: `${duration}ms`,
requestId: requestId,
timestamp: new Date().toISOString()
});
throw new Error(`${apiName} returned ${response.status}`);
}
console.log({
level: 'info',
api: apiName,
duration: `${duration}ms`,
requestId: requestId,
timestamp: new Date().toISOString()
});
return response.json();
} catch (error) {
console.error({
level: 'error',
api: apiName,
error: error.message,
requestId: requestId,
timestamp: new Date().toISOString()
});
throw error;
}
}
このログはCloudflare Workers Analyticsで集約でき、後からダッシュボードで検索・分析できます。エラーハンドリングはエラーが起きたときに「どうエラーを処理するか」だけでなく、「後から何が起きたのか証跡を残すか」も同じくらい重要です。
京谷商会では、複数クライアントのAPI連携ログを一元監視するダッシュボードを構築しており、①平均応答時間②エラー発生率③API別呼び出し回数を自動集計しています。この情報から「毎月末にジョブカンの給与明細取得がレート制限に引っかかるため、取得時間を分散させる必要がある」といった改善施策が自動的に洗い出せます。
複数API連携を一元管理する設計パターン
実際のプロジェクトでは、単一のAPI呼び出しではなく、複数システム（freee＋ジョブカン＋Chatwork等）が連携することがほとんどです。API ごとに認証・エラーハンドリング・ログを分散実装すると、後のメンテナンスが困難になります。
Cloudflare Workersで複数API連携を管理する場合、全外部API呼び出しを一つの関数に集約し、認証・リトライ・ログを統一管理する「API Integration Hub」パターンが有効です。
| パターン | 認証方式 | セキュリティ | 実装難度 | 推奨用途 |
|---|---|---|---|---|
| APIキー＋環境変数 | APIキー | 高 | 低 | freee・Chatwork等の社内向けAPI連携 |
| OAuth 2.0 | トークン交換 | 最高 | 高 | LINE・Slackなどユーザー認可が必要なケース |
| Basic認証＋HTTPS | ID＋パスワード（Base64） | 中 | 低 | レガシーシステムとの連携 |
| API Keyのローテーション | 定期更新 | 最高 | 中 | 長期運用するシステム |
// src/apis/apiHub.js — 全API設定を一元管理
const API_CONFIGS = {
freee: {
baseUrl: 'https://api.freee.co.jp/api/1',
authType: 'bearer',
tokenKey: 'FREEE_API_TOKEN',
rateLimit: { requests: 300, period: 60 },
},
jobcan: {
baseUrl: 'https://api.jobcan.jp/api/v1',
authType: 'apikey',
tokenKey: 'JOBCAN_API_KEY',
rateLimit: { requests: 60, period: 60 },
},
chatwork: {
baseUrl: 'https://api.chatwork.com/v2',
authType: 'bearer',
tokenKey: 'CHATWORK_TOKEN',
rateLimit: { requests: 100, period: 60 },
}
};
export async function callAPI(apiName, method, endpoint, body = null) {
const config = API_CONFIGS[apiName];
const token = env[config.tokenKey];
const url = `${config.baseUrl}${endpoint}`;
const headers = buildAuthHeaders(config.authType, token);
const options = {
method,
headers,
...(body && { body: JSON.stringify(body) })
};
return fetchWithRetry(url, options, apiName);
}
function buildAuthHeaders(authType, token) {
if (authType === 'bearer') {
return { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' };
}
if (authType === 'apikey') {
return { 'X-API-Key': token, 'Content-Type': 'application/json' };
}
return {};
}
このハブ方式により、新しいAPIを追加する際は設定値を追加するだけで、認証・エラーハンドリング・ログはすべて自動的に機能します。その結果、複数API管理のメンテナンスコストが1/3以下に削減できます。
地方中小企業がAPI連携を実装するときの実務ステップ
地方中小企業がCloudflare Workersを使ってAPI連携を実装する際、「APIドキュメントを整理してから設計・実装を始める」というステップが最も重要です。手順は以下の通りです。
まず、連携対象のAPI提供者の仕様書から①認証方式（APIキー、OAuth 2.0、Basic認証のいずれか）②レート制限の上限と時間単位③エラーレスポンスの形式④タイムアウト仕様の4点を確認します。次に、この4点に基づいて上記のAPI Integration Hubパターンを選択し、環境変数でトークンを管理します。最後に、リトライロジックとエラーログを実装し、Cloudflare Workers Analyticsで監視する仕組みを整えます。
この「契約から実装へ」という原理原則を守ることで、後のトラブルシューティングにかかる時間を大幅に削減でき、また追加のAPI連携が必要になった際もコードの大幅な書き直しを避けられます。
よくある質問
Q1. APIキーはCloudflare Workers KVに保存してもいいですか？
A: 推奨しません。KVはデータキャッシュ用で、秘密情報の長期保存には設計されていません。代わりに、Cloudflareダッシュボードの「環境変数」セクションで設定し、デプロイ時に自動注入される仕組みを使用してください。APIキーを定期的にローテーション（交換）する場合も、ダッシュボード側で変更するだけでWorkers側のコードはそのままです。
Q2. OAuth 2.0トークンが期限切れになったとき、自動更新するにはどうするか？
A: リフレッシュトークンを使用して新トークンを取得します。重要な実装は、①アクセストークン取得時にリフレッシュトークンも受け取る、②有効期限とともにWorkers KVに保存する、③API呼び出し時に有効期限をチェックして期限切れなら自動更新する、④更新後の新トークンでリトライするという4ステップです。詳細はCloudflareの公式ドキュメント——環境変数とシークレットの管理を参照してください。
Q3. 複数の外部APIを並列で呼び出して高速化したいが、エラー発生時の部分的な失敗をどう扱うか？
A: Promise.allSettled()を使用し、全APIの完了を待った後に個別に成功・失敗を判定します。Promise.all()は一つ失敗するとすべて失敗になりますが、allSettled()なら個別処理が可能です。例えば、freeeと給与システム連携で、どちらか一方が失敗しても、成功した側のデータを部分的に保存できます。