2026/06/04

PDF生成 リアルタイム進捗ストリーミング完全ガイド — SSEとX-Job-Idの使い方

sserealtimeapistreamingpdf

ポーリングとWebhookによるPDF生成ステータス追跡を紹介した記事では、PDFジョブの状態を確認する2つの代表的なアプローチを取り上げました。本記事ではその延長として、第3の選択肢 — Server-Sent Events (SSE) によるリアルタイム進捗ストリーミングを紹介します。

FUNBREW PDF APIは2026年5月31日のアップデートで、バッチジョブと単発生成ジョブの両方に対してSSEエンドポイントを追加しました。進捗バーやステータス表示を画面にリアルタイム反映したい場合に向いた仕組みです。

ポーリング・Webhook・SSEの3択比較

ポーリング Webhook SSE
リアルタイム性 インターバル遅延あり あり あり
公開の受信エンドポイントが必要 不要 必要 不要
ブラウザから使う方法 自前のバックエンド経由 不可 自前のバックエンド経由
余分なAPIコール あり なし なし
中間進捗(%)を取得できる 不可 不可 可能
再接続時の取りこぼし防止 別途実装が必要 配信失敗時の再試行(計3回まで) Last-Event-ID で続きから
向いているシーン CLIスクリプト・シンプルなサーバー処理 サーバー間の完了通知 進捗表示・ブラウザUI

ポーリングの対象はバッチの状態(GET /api/pdf/batch/{batch_id})です。単発生成(/api/pdf/generate-from-html 等)は同期APIで、レスポンスが返った時点でPDFはできています。

SSEの最大の利点は「公開HTTPエンドポイントを用意せずに、生成中の中間進捗を受け取れる」点です。ただしAPIキーはヘッダで送る必要があり、ブラウザ標準の EventSource はヘッダを付けられません(後述)。ブラウザに表示する場合は、自前のバックエンドがAPIキー付きで購読し、ブラウザへ中継します。

SSEとは

Server-Sent Events (SSE) はHTTP上でサーバーからクライアントへのプッシュ配信を行う仕組みです。text/event-stream Content-Typeで接続を維持し、サーバーが随時データを送り込みます。

  • 通常のHTTPレスポンス — WebSocketのようなプロトコルの切り替えは不要
  • ブラウザ標準 — EventSource APIで受信できる
  • 自動再接続 — HTML仕様で、接続が閉じるとクライアントは再接続すると定められている
  • 取りこぼし防止 — 再接続時に Last-Event-ID ヘッダで最後に受け取ったIDをサーバーへ伝えられる

FUNBREW PDF APIのSSEエンドポイント

エンドポイント仕様

GET /api/pdf/jobs/{jobId}/events
Accept: text/event-stream
Authorization: Bearer sk-xxxx      # または X-API-Key: sk-xxxx
Last-Event-ID: <id>    # 任意。前回受信した最後のIDを指定すると続きから受信

jobId は2種類の方法で取得します。

ジョブの種類 jobIdの取得方法
バッチ生成 POST /api/pdf/batch のレスポンス(201)の batch_id
単発生成 (/generate-from-html 等) レスポンスヘッダの X-Job-Id、またはリクエスト時に X-Job-Id ヘッダで自分で指定

X-Job-Id は単発生成のほか、merge・compress・extract-text・to-image でも同じように使えます。ただし generate-from-template は X-Job-Id に対応しておらず、進捗を購読できません。

認証: PDF APIキーを Authorization: Bearer または X-API-Key ヘッダで送ります。APIキーには download スコープが必要です。このエンドポイントは毎分のレート制限・月間の生成数の対象外です。SaaS版では、自社のバッチ、または自社のAPIキーで投入したジョブのIDだけを購読でき、それ以外は404になります。

X-Job-Idヘッダの役割

単発生成は同期APIなので、生成リクエストのレスポンスが返る時点でジョブは終わっています。生成中の進捗を見たい場合は、X-Job-Id を使って生成リクエストの実行中にSSEを購読します。

  • 自分で指定: UUID等を自分で生成し、X-Job-Id ヘッダを付けて生成リクエストを送ります。そのリクエストがサーバーに届いた後に同じIDでSSEを開くと、進捗をリアルタイムに受け取れます
  • 🔴 SSEを先に開くと404: SaaS版では、生成リクエストがサーバーに届いてジョブIDが自社に紐付くまで、SSEは404を返します。生成リクエストを送ってから購読するか、404なら少し待って再試行してください(紐付けは1時間有効)
  • 事後取得: X-Job-Id を省くと、サーバーがUUIDを発行してレスポンスヘッダ X-Job-Id で返します。この時点でジョブは終わっているため、SSEを開くと保持されている履歴(done まで)がまとめて届きます

イベントの種類とペイロード

SSEストリームは接続直後の retry 指定と、progress という名前のイベントを配信します。

retry: 3000

id: 1748649600123-0
event: progress
data: {"phase":"queued","progress":0.0,"message":"received","data":{},"occurred_at":"2026-05-31T01:00:00+00:00"}

id: 1748649600456-0
event: progress
data: {"phase":"rendering","progress":0.2,"message":"rendering html","data":{},"occurred_at":"2026-05-31T01:00:01+00:00"}

id: 1748649600789-0
event: progress
data: {"phase":"done","progress":1.0,"message":"completed","data":{"filename":"...","download_url":"..."},"occurred_at":"2026-05-31T01:00:02+00:00"}

progress は 0.0〜1.0 の割合です。単発生成の done では data に filename と download_url が入ります。バッチの done(または全件失敗時の failed)では data に batch_id・total_items・completed_items・failed_items が入ります。

フェーズ一覧:

phase 意味
queued リクエスト受付
preprocessing 入力PDFの解決(merge・compress・extract-text・to-image のみ)
rendering PDFレンダリング・処理中
postprocess 透かしなどの後処理(単発生成・バッチ)
uploading 生成したPDFの保存中
done 完了(終端 — サーバーがストリームを閉じる)
failed 失敗(終端 — サーバーがストリームを閉じる)

done または failed を送るとサーバー側がストリームを閉じます。クライアント側でも終端を受け取ったら接続を閉じてください(EventSource は閉じられた接続に再接続しようとします)。

実装例

curlで試す(最も手軽)

# バッチジョブの場合
curl -N \
  -H "Authorization: Bearer $FUNBREW_PDF_API_KEY" \
  https://pdf.funbrew.cloud/api/pdf/jobs/<batch_id>/events

-N(--no-buffer)を付けると、届いたイベントがそのまま表示されます。curlは通常、出力をまとめて書き出すため、付けないとリアルタイムに見えないことがあります。

単発生成の進捗を見る場合(生成リクエストを先に送り、実行中に購読する):

# 1. jobIdを自分で生成
JOB_ID=$(uuidgen)

# 2. 同じjobIdで生成リクエストを投入(同期APIなのでバックグラウンドで実行)
curl -s -X POST https://pdf.funbrew.cloud/api/pdf/generate-from-html \
  -H "Authorization: Bearer $FUNBREW_PDF_API_KEY" \
  -H "X-Job-Id: $JOB_ID" \
  -H "Content-Type: application/json" \
  -d '{"html":"<h1>Hello FUNBREW PDF</h1>"}' > result.json &

# 3. リクエストがサーバーに届くのを少し待ってからSSEを購読
sleep 1
curl -N -H "Authorization: Bearer $FUNBREW_PDF_API_KEY" \
  "https://pdf.funbrew.cloud/api/pdf/jobs/$JOB_ID/events"

数秒で終わる短いHTMLでは、購読した時点で既に done まで進んでいることがあります。その場合も保持されている履歴がまとめて届きます。

生成後にレスポンスヘッダからJobIdを取得する方法(履歴を確認する用途):

# ヘッダ付きでレスポンスを受け取る
RESP=$(curl -sD - -X POST https://pdf.funbrew.cloud/api/pdf/generate-from-html \
  -H "Authorization: Bearer $FUNBREW_PDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html":"<h1>Hello FUNBREW PDF</h1>"}')

JOB_ID=$(echo "$RESP" | grep -i 'X-Job-Id' | cut -d' ' -f2 | tr -d '\r')

# SSE購読(ジョブは終わっているので queued 〜 done の履歴が届く)
curl -N -H "Authorization: Bearer $FUNBREW_PDF_API_KEY" \
  "https://pdf.funbrew.cloud/api/pdf/jobs/$JOB_ID/events"

サーバー側で購読する(Node.js 18以降・fetch)

APIキーはヘッダで送る必要があるため、サーバー側では fetch でストリームを読むのが確実です。Node.js 18以降の組み込み fetch で動きます(追加パッケージ不要)。

const baseUrl = 'https://pdf.funbrew.cloud';
const apiKey = process.env.FUNBREW_PDF_API_KEY;

async function streamJobEvents(jobId, onEvent) {
  const res = await fetch(`${baseUrl}/api/pdf/jobs/${jobId}/events`, {
    headers: {
      Authorization: `Bearer ${apiKey}`,
      Accept: 'text/event-stream',
    },
  });
  if (!res.ok) throw new Error(`SSE HTTP ${res.status}`); // 404 なら少し待って再試行

  const decoder = new TextDecoder();
  let buffer = '';
  for await (const chunk of res.body) {
    buffer += decoder.decode(chunk, { stream: true });
    let sep;
    while ((sep = buffer.indexOf('\n\n')) !== -1) {
      const block = buffer.slice(0, sep);
      buffer = buffer.slice(sep + 2);
      const dataLine = block.split('\n').find((line) => line.startsWith('data: '));
      if (!dataLine) continue; // retry: 行など
      const payload = JSON.parse(dataLine.slice(6));
      onEvent(payload);
      if (payload.phase === 'done' || payload.phase === 'failed') return payload;
    }
  }
}

const batchId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
const last = await streamJobEvents(batchId, (p) => {
  console.log(`[${p.phase}] ${Math.round(p.progress * 100)}% — ${p.message}`);
});
process.exit(last?.phase === 'done' ? 0 : 1);

ブラウザ EventSource API(自前のバックエンドで中継)

ブラウザ標準の EventSource のコンストラクタで指定できるオプションは withCredentials だけで、Authorization などのヘッダは付けられません。APIキーをブラウザに露出させないためにも、自前のバックエンドに中継用のエンドポイント(下の例では /progress/{jobId})を用意し、バックエンドが上の fetch でAPIキー付きで購読して、受け取った内容をそのままブラウザへ流します。

const jobId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'; // batch_id または X-Job-Id

// 自前のバックエンドの中継エンドポイント(APIキーはバックエンド側で付与)
const es = new EventSource(`/progress/${jobId}`);

es.addEventListener('progress', (event) => {
  const payload = JSON.parse(event.data);

  // 進捗バーを更新
  updateProgressBar(payload.progress); // 0.0 〜 1.0

  // フェーズに応じてUIを更新
  showStatus(payload.phase, payload.message);

  // 終端フェーズで購読を終了
  if (payload.phase === 'done' || payload.phase === 'failed') {
    es.close();
    if (payload.phase === 'done') {
      console.log('完了:', payload.data);
    } else {
      console.error('失敗:', payload.message);
    }
  }
});

es.onerror = (err) => {
  // EventSourceは自動で再接続し、最後に受け取ったIDを Last-Event-ID ヘッダで送る。
  // 中継側がこのヘッダをFUNBREW PDF APIへ転送すれば、続きから受信できる。
  console.warn('SSE接続エラー(自動再接続中):', err);
};

中継側は id:・event:・data: の行をそのまま流し、ブラウザから届いた Last-Event-ID をFUNBREW PDF APIへのリクエストに付けてください。

@funbrew/pdf-client SDK

JS SDK (@funbrew/pdf-client) には subscribeToJob() がありますが、現時点ではSSEの購読に使えません。SDKはAPIキーをクエリ文字列(?api_key=)で送りますが、APIはキーをヘッダからしか読まないため、購読は認証エラーになります。

SDKは生成リクエストに X-Job-Id を付ける用途で使い、進捗の購読は上の fetch の例で行ってください。

import { PdfClient } from 'https://pdf.funbrew.cloud/sdk/pdf-client.esm.js';

// APIキーを扱うため、サーバー側(またはAPIキーを露出してよい社内ツール)で使う
const client = new PdfClient({
  baseUrl: 'https://pdf.funbrew.cloud',
  apiKey: process.env.FUNBREW_PDF_API_KEY,
});

// 1. jobIdを先に決める
const jobId = crypto.randomUUID();

// 2. 同じjobIdでジョブを投入(generateFromHtml は X-Job-Id ヘッダを付けて送る)
const pending = client.generateFromHtml(
  { html: '<h1>Hello FUNBREW PDF</h1>', options: { 'page-size': 'A4' } },
  { jobId }
);

// 3. 実行中に進捗を購読(上の streamJobEvents)
await new Promise((r) => setTimeout(r, 500));
await streamJobEvents(jobId, (p) => updateProgressBar(p.progress));

const result = await pending;
console.log('PDF生成完了:', result);

単発生成のフェーズ遷移: queued → rendering → postprocess → uploading → done(失敗時: failed)

ポーリング・Webhook・SSEの使い分けマトリクス

シナリオ 推奨アプローチ
ブラウザに進捗バーを表示したい SSE(バックエンドで中継)
CLIスクリプト・cronジョブ ポーリング
サーバー間の完了通知 Webhook
公開の受信サーバーが持てない SSE またはポーリング
長時間のバッチ SSE + Webhook の併用
短時間の単発生成 同期API(ポーリング不要)
同時に多数のジョブを追う Webhook(SSEはジョブごとに長時間の接続を1本使う)

SSEとWebhookの併用: SSEは「ユーザーが画面を見ている間の進捗表示」、Webhookは「PDFができたことのサーバーへの通知」と役割が異なります。UI表示はSSE・バックエンド処理のトリガーはWebhookと使い分けるのが扱いやすい構成です。

注意点と運用ヒント

以下の「PHP-FPM」「Nginx」「環境変数」の節は、Open エディションを自分のサーバーで動かす場合の話です。SaaS版(pdf.funbrew.cloud)を使う場合は設定不要です。自前のバックエンドで中継する場合は、中継側のプロキシでも同じバッファリングの注意が当てはまります。

PHP-FPMのワーカー占有

SSE接続中はPHP-FPMワーカーが1つ専有されます。大量の同時接続が見込まれる場合は、SSE用にワーカー数を増やした専用のFPMプールを分けるなど、接続数に見合ったワーカーを確保してください。

Nginxの設定

location /api/pdf/jobs/ {
    proxy_pass http://app;
    proxy_buffering off;          # バッファされるとリアルタイムにならない
    proxy_cache off;
    proxy_read_timeout 3600s;     # 長時間の接続に対応
    proxy_http_version 1.1;
    proxy_set_header Connection '';
}

レスポンスヘッダに X-Accel-Buffering: no が付いているため、Nginxはこのレスポンスのバッファリングを無効にします(proxy_ignore_headers でこのヘッダを無視する設定にしていない場合)。proxy_buffering off を明示しておくと確実です。

タイムアウトと最大接続時間

1接続の最大保持時間(既定600秒)を超えると、サーバーがストリームを閉じます。EventSource の自動再接続と Last-Event-ID により、切断後も続きから受信できます。

環境変数 デフォルト 説明
PDF_PROGRESS_MAX_DURATION 600 1接続あたりの最大保持時間(秒)
PDF_PROGRESS_POLL_MS 500 サーバー側で新しいイベントを確認する間隔(ms)
PDF_PROGRESS_TTL 86400 進捗履歴(Redis)の保持時間(秒)

再接続と取りこぼし防止

Last-Event-ID ヘッダを使うと、切断前に受信した最後のイベントIDの続きからストリームを取得できます。ブラウザの EventSource は再接続時にこのヘッダを自動で付けます。

IDはRedis StreamのID(<ミリ秒>-<連番> 形式)です。履歴は1ジョブあたり約1000件・既定24時間保持されます。

古いIDへの対応

Last-Event-ID が保持されている最古のイベントより古い場合、サーバーは 410 Gone を返します。この場合は Last-Event-ID を付けずに再接続すると、保持されている履歴を最初から受け取れます。バッチなら GET /api/pdf/batch/{batch_id} で件数を確認することもできます。

まとめ

FUNBREW PDF APIのSSEストリーミングは、ポーリングとWebhookに続く第3の選択肢として、特にリアルタイムの進捗表示に適しています。

  • APIキーはヘッダで送る。ブラウザに表示する場合は自前のバックエンドで中継する
  • バッチ・単発ジョブ両方に対応。単発ジョブは X-Job-Id で、生成リクエストの実行中に購読する
  • Last-Event-ID による取りこぼし防止 — 再接続時も続きから受信
  • SDKの subscribeToJob は現時点では認証できないため、fetch で購読する

長時間のバッチで進捗バーを表示しながら、完了後の処理はWebhookで行う「SSE + Webhookの併用」が扱いやすい構成です。

関連リンク

Powered by FUNBREW PDF