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

Ktorクライアントで必要となるアーティファクトについては、「

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

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

」から詳細を確認できます。

WebSocketsのインストール

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

設定

オプションで、installブロック内でプラグインを構成するには、WebSockets.Configのサポートされているプロパティを渡します。

maxFrameSize

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

contentConverter

シリアル化/デシリアル化のためのコンバーターを設定します。

pingIntervalMillis

Long形式でピング間の期間を指定します。

pingInterval

Duration形式でピング間の期間を指定します。

以下の例では、WebSocketsプラグインが20秒（20_000ミリ秒）のピング間隔で構成され、ピングフレームを自動的に送信してWebSocket接続を維持します。

WebSocketセッションの操作

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

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

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

• webSocket()関数は、DefaultClientWebSocketSessionをブロック引数として受け入れます。
• webSocketSession()関数は、DefaultClientWebSocketSessionインスタンスを返し、runBlockingまたはlaunchスコープの外でセッションにアクセスできます。

WebSocketセッションの処理

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

send()

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

outgoing

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

incoming

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

close()

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

フレームタイプ

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

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

例

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

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