2011年2月27日日曜日

Channel API ドキュメント日本語要約 (Google App Engine)

 

概要

Channel APIはアプリケーションとgoogleサーバーの間に持続的な接続を作り、JavaScriptクライアントにポーリングを使わずにリアルタイムにメッセージを送ることができる。

Channel APIの要素

JavaScriptクライアント

クライアントの役割

  • チャネルに接続してサーバからチャネルのユニークなトークンを受け取る。
  • ほかのクライアントのアップデートを待ち受けて、データを使用する。
  • アップデートをサーバーに送信する。
サーバ

サーバの役割

  • 個々のJavaScriptクライアントにユニークなチャネルを作る。
  • ユニークトークンを作りJavaScriptクライアントに送る。
  • クライアントからのアップデートをPOSTで受ける。
  • チャネルを使ってクライアントにアップデートメッセージを送る。
クライアントID

クライアントIDはサーバでそれぞれのJavaScriptクライアントを識別するためのもの。クライアントIDはアプリケーションでどのように設計しても良い。

トークン

トークンはJavaScriptクライアントがチャネルに接続して待ち受けることを可能にする役割がある。

サーバはそれぞれのクライアントのためにクライアントIDと有効期限などの情報を使って トークンを作成する。

チャネル

チャネルはサーバーがクライアントIDで識別されるJavaScriptクライアントにアップデートを送るための片方向の通信路。

サーバはクライアントからPOSTによってアップデートを受信すると、該当するクライアントにチャネルを使ってメッセージを送る。

メッセージ

メッセージはクライアントからサーバにPOSTによって送られる。

受信すると、サーバはクライアントIDで識別されたクライアントにチャネルを使ってメッセージを渡す。

メッセージは32KBまで。

URLを送るときに生のメッセージで送るのは避ける。その代わりにメッセージが損なわれずに到達するようにJSONエンコーディングを使う。

ソケット

JavaScriptクライアントはサーバから提供されたトークンを使ってソケット開く。チャネルで更新を待ち受けるためにソケットを使う。

Channel APIを使うためのコード

チャネルを作る(サーバ)

channelServiceを取得して、チャネルを作成。トークンを生成する。

ChannelService channelService =
  ChannelServiceFactory.getChannelService();
String token = channelService.createChannel(clientId);

チャネルに接続する(クライアント)

サーバからもらったトークンを使ってチャネルを開く。

channel = new goog.appengine.Channel(token);
socket = channel.open();
socket.onopen = onOpened;
socket.onmessage = onMessage;
socket.onerror = onError;
socket.onclose = onClose;

サーバーからクライアントへのメッセージ送信(サーバ)

channelService.sendMessage(
  new ChannelMessage(clientId, messageString));

トークンとセキュリティ

createChannel()によって返されるトークンは他に知られないように秘密にしておく。もしトークンが盗まれたらチャネルに送られたメッセージを待ち受けできてしまう。

トークンは2時間で期限切れになる。クライアントが2時間以上チャネルに接続したままでいると、ソケットのonerror(), onclose()がコールバックされる。

注意

クライアントID毎に1つのクライアント

1つのクライアントIDで一度にチャネルに接続できるのは1つのクライアントだけ。アプリケーションは1つのクライアントIDでメッセージを多数のクライアントにばら撒くことはできない。

ページ毎に1つのチャネル、チャネル毎に1つのクライアント

クライアントは1ページにつき1つのチャネルにだけ接続できる。

もしアプリケーションがクライアントに複数の種類のデータを送る必要があるならサーバサイドでデータを集めてクライアントのソケットのonmessageハンドラに送る。

クライアントの接続と切断の追跡

チャネルに接続したクライアントには"プレゼンス"の概念がない。これはクライアントのチャネルへの接続または切断についてアプリケーションに通知されないことを意味する。

もし、アプリケーションがクライアントの接続を追跡する必要があるなら、1つの方法としてクライアントの状態を通知するために適当な間隔でPOSTメッセージをサーバに送るよう設計された関数をソケットのonopenプロパティにセットする。