サーバー送信イベントの使用

サーバーからのイベントの受信

サーバー送信イベント API は EventSource インターフェイスに含まれています。

EventSource インスタンスの作成

イベントを受け取るためにサーバーへの接続を開始するには、新たな EventSource オブジェクトを作成し、イベントを生成するスクリプトの URI を指定します。例を挙げます。

const evtSource = new EventSource("ssedemo.php"); 

イベントを生成するスクリプトが別のオリジンに存在する場合は、 新しい EventSource オブジェクトを作成し、 URI とオプション辞書の両方を指定する必要があります。例えば、クライアントスクリプトが example.com にある場合は次のようになります。

const evtSource = new EventSource("//api.example.com/ssedemo.php", { withCredentials: true, }); 

message イベントの待ち受け

イベントソースのインスタンスを起動したら、 message イベントのハンドラーを取り付けて、サーバーからのメッセージを待ち受けすることができます。

evtSource.onmessage = (event) => { const newElement = document.createElement("li"); const eventList = document.getElementById("list"); newElement.textContent = `message: ${event.data}`; eventList.appendChild(newElement); }; 

このコードは入力メッセージを受信して、メッセージのテキストを文書の HTML にあるリストへ追加します。

カスタムイベントの待ち受け

event フィールドが定義されているサーバーからのメッセージは、event で指定された名前のイベントとして受信されます。例を示します。

evtSource.addEventListener("ping", (event) => { const newElement = document.createElement("li"); const eventList = document.getElementById("list"); const time = JSON.parse(event.data).time; newElement.textContent = `ping at ${time}`; eventList.appendChild(newElement); }); 

このコードは、サーバーが event フィールドを ping に設定したメッセージを送信するたびに呼び出されます。こちらは data フィールドの JSON を解釈して、情報を出力します。

サーバーからのイベントの送信

イベントを送信するサーバー側のスクリプトは、 MIME タイプ text/event-stream で応答する必要があります。個々の通知は、 2 つの改行で終わるテキストのブロックとして送信されます。イベントストリームの形式について、詳しくはイベントストリーム形式をご覧ください。

この例で使用している PHP は次の通りです。

date_default_timezone_set("America/New_York"); header("X-Accel-Buffering: no"); header("Content-Type: text/event-stream"); header("Cache-Control: no-cache"); $counter = rand(1, 10); while (true) { // "ping" イベントを毎秒送信 echo "event: ping\n"; $curDate = date(DATE_ISO8601); echo 'data: {"time": "' . $curDate . '"}'; echo "\n\n"; // シンプルなメッセージをランダムな間隔で送信 $counter--; if (!$counter) { echo 'data: This is a message at time ' . $curDate . "\n\n"; $counter = rand(1, 10); } if (ob_get_contents()) { ob_end_flush(); } flush(); // クライアントが接続を中止したら（ページを閉じたら）ループから抜ける if (connection_aborted()) break; sleep(1); } 

上記のコードは、イベント種別が "ping" のイベントを毎秒生成します。それぞれのイベントのデータは、 JSON オブジェクトで、イベントが生成された時刻を ISO 8601 形式のタイムスタンプで表します。またランダムな間隔で、単純なメッセージ（イベント種別なし）を送信します。 ループは接続状態にかかわらず実行し続けられますので、接続が閉じられたとき（例えばクライアントがページを閉じたとき）にループから脱出するためのチェックが含まれています。

エラー処理

問題が発生した場合（ネットワークのタイムアウトやアクセス制御に関する問題など）は、エラーイベントが生成されます。これをプログラムで処理するには、 onerror コールバックを EventSource に実装してください。

evtSource.onerror = (err) => { console.error("EventSource failed:", err); }; 

イベントストリームを閉じる

既定では、クライアントとサーバーの間の接続を閉じると、接続が再起動します。接続は .close() メソッドで終了します。

evtSource.close(); 

イベントストリームの形式

イベントストリームは単純なテキストデータのストリームで、 UTF-8 でエンコードされていなければなりません。イベントストリームのメッセージは、 2 つの改行文字で区切られます。行の先頭の文字がコロンであった場合はコメントとみなされ、無視されます。

それぞれのメッセージは、そのメッセージのフィールドを列挙した 1 行以上のテキストで構成されています。各フィールドは、フィールド名、コロン、そのフィールドの値のテキストデータで表現されます。

フィールド

受信した各メッセージには、以下のフィールドの組み合わせが、 1 行 1 つで現れます。

event

記述されるイベントの種別を識別する文字列です。指定された場合、イベントはブラウザー内で、指定されたイベント名のイベントリスナーへ送られます。ウェブサイトのソースコードで名前付きイベントを待ち受けするには addEventListener() を使用してください。メッセージにイベント名が指定されなかった場合は、 onmessage ハンドラーが呼び出されます。

data

メッセージのデータフィールドです。 EventSource が data: で始まる、複数の連続した行を受け取ったときは、それらを連結して各項目の間に改行文字を挿入します。末尾の改行は取り除かれます。

id

EventSource オブジェクトの最後のイベント ID の値に設定するイベント ID です。

retry

再接続時間です。サーバーへの接続が切れた場合、ブラウザーは指定した時間だけ待ってから再接続を試みます。これは整数値でなければならず、再接続時間をミリ秒単位で指定します。整数値以外が指定された場合は、このフィールドは無視されます。

他のフィールド名は、すべて無視されます。

例

データのみのメッセージ

以下の例では、3 つのメッセージが送信されています。最初のメッセージはコロン文字から始まっているため、コメントです。前述したように、コメントはメッセージが定期的に送信されない可能性がある場合のキープアライブとして利用できます。

2 番目のメッセージには data フィールドがあり、その値は "some text" です。 3 番目のメッセージは data フィールドで、値は "another message\nwith two lines" です。値に改行文字があることに注意してください。

: this is a test stream data: some text data: another message data: with two lines 

名前付きイベント

こちらの例では、名前付きイベントをいくつか送信しています。それぞれのイベントではイベント名が event フィールドで指定されており、また data フィールドではクライアントでの処理に必要なデータを含む、適切な JSON 文字列の値が指定されています。もちろん、 data フィールドには任意の文字列データを入れることができます。 JSON である必要はありません。

event: userconnect data: {"username": "bobby", "time": "02:33:48"} event: usermessage data: {"username": "bobby", "time": "02:34:11", "text": "Hi everyone."} event: userdisconnect data: {"username": "bobby", "time": "02:34:23"} event: usermessage data: {"username": "sean", "time": "02:34:36", "text": "Bye, bobby."} 

組み合わせ

名前なしのメッセージや種類の付いたイベントだけを使用しなければならない訳ではありません。これらを単一のイベントストリーム内で混用することができます。

event: userconnect data: {"username": "bobby", "time": "02:33:48"} data: Here's a system message of some kind that will get used data: to accomplish some task. event: usermessage data: {"username": "bobby", "time": "02:34:11", "text": "Hi everyone."} 

ブラウザーの互換性