WebSockets

Client Plugin

Ktor ClientにおけるWebSockets

必要な依存関係: io.ktor:ktor-client-websockets

コード例: client-websockets

WebSocketは、単一のTCP接続を介してユーザーのブラウザとサーバー間にフルデュプレックス（全二重）通信セッションを提供するプロトコルです。これは、サーバーとの間でのリアルタイムのデータ転送が必要なアプリケーションを作成する場合に特に有用です。 Ktorは、サーバー側とクライアント側の両方でWebSocketプロトコルをサポートしています。

クライアント用のWebSocketsプラグインを使用すると、サーバーとメッセージを交換するためのWebSocketセッションを処理できます。

NOTE

すべてのエンジンがWebSocketsをサポートしているわけではありません。サポートされているエンジンの概要については、制限事項を参照してください。

TIP

サーバー側のWebSocketサポートについては、

Ktor ServerにおけるWebSockets

WebSocketsプラグインを使用すると、サーバーとクライアント間で多方向の通信セッションを作成できます。

を参照してください。

依存関係の追加

WebSocketsを使用するには、ビルドスクリプトに ktor-client-websockets アーティファクトを含める必要があります。

Gradle (Kotlin)Gradle (Groovy)Maven

TIP

Ktorクライアントに必要なアーティファクトの詳細については、

クライアントの依存関係の追加

既存のプロジェクトにクライアントの依存関係を追加する方法を学びます。

を参照してください。

WebSocketsのインストール

WebSocketsプラグインをインストールするには、クライアント設定ブロック内の install 関数に渡します。

設定

オプションで、WebSockets.Config のサポートされているプロパティを渡すことで、install ブロック内でプラグインを設定できます。

<code>maxFrameSize</code>

受信または送信可能な Frame の最大サイズを設定します。

<code>contentConverter</code>

シリアライズ/デシリアライズ用のコンバーターを設定します。

<code>pingIntervalMillis</code>

pingの間隔を Long 形式で指定します。

<code>pingInterval</code>

pingの間隔を Duration 形式で指定します。

pingInterval および pingIntervalMillis プロパティは、OkHttpエンジンには適用されません。OkHttpのping間隔を設定するには、エンジン設定を使用できます。

以下の例では、WebSocketsプラグインを20秒（20_000ミリ秒）のping間隔で設定し、pingフレームを自動的に送信してWebSocket接続を維持するようにしています。

WebSocketセッションの操作

クライアントのWebSocketセッションは、DefaultClientWebSocketSession インターフェースによって表されます。このインターフェースは、WebSocketフレームの送受信やセッションのクローズを可能にするAPIを公開しています。

WebSocketセッションへのアクセス

HttpClient は、WebSocketセッションにアクセスするための2つの主要な方法を提供します。

• webSocket() 関数は、ブロック引数として DefaultClientWebSocketSession を受け取ります。
• webSocketSession() 関数は DefaultClientWebSocketSession インスタンスを返し、runBlocking や launch スコープの外でセッションにアクセスすることを可能にします。

WebSocketセッションの処理

関数ブロック内で、指定されたパスのハンドラーを定義します。ブロック内では以下の関数とプロパティが利用可能です。

<code>send()</code>

サーバーにテキストコンテンツを送信するには、send() 関数を使用します。

<code>outgoing</code>

WebSocketフレームを送信するためのチャネルにアクセスするには、outgoing プロパティを使用します。フレームは Frame クラスによって表されます。

<code>incoming</code>

WebSocketフレームを受信するためのチャネルにアクセスするには、incoming プロパティを使用します。フレームは Frame クラスによって表されます。

<code>close()</code>

指定された理由でクローズフレームを送信するには、close() 関数を使用します。

フレームの種類

WebSocketフレームのタイプを確認し、それに応じて処理できます。一般的なフレームタイプは以下の通りです。

• Frame.Text はテキストフレームを表します。内容を読み取るには Frame.Text.readText() を使用します。
• Frame.Binary はバイナリフレームを表します。内容を読み取るには Frame.Binary.readBytes() を使用します。
• Frame.Close はクローズフレームを表します。セッション終了の理由を取得するには Frame.Close.readReason() を使用します。

例

以下の例では、echo WebSocketエンドポイントを作成し、サーバーとの間でメッセージを送受信する方法を示します。

完全な例については、client-websockets を参照してください。