Skip to content
Client Plugin

Ktor ClientのWebSockets

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

コード例: client-websockets

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

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

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

サーバー側でのWebSocketサポートについては、Ktor ServerのWebSocketsWebsockets プラグインを使用すると、サーバーとクライアント間で双方向の通信セッションを作成できます。を参照してください。

依存関係の追加

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

kotlin
implementation(ktorLibs.client.websockets)
上記のコードスニペットでは、Ktorの依存関係を指定するためにKtorバージョンカタログを使用しています。
groovy
implementation ktorLibs.client.websockets
上記のコードスニペットでは、Ktorの依存関係を指定するためにKtorバージョンカタログを使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-websockets-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>
Ktorクライアントに必要なアーティファクトの詳細については、クライアント依存関係の追加既存のプロジェクトにクライアントの依存関係を追加する方法を学びます。を参照してください。

WebSocketsのインストール

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

kotlin
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.websocket.*

//...
val client = HttpClient(CIO) {
    install(WebSockets)
}

設定

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

maxFrameSize
送受信可能な最大Frameサイズを設定します。
contentConverter
シリアライズ/デシリアライズ用のコンバーターを設定します。
pingIntervalMillis
Pingの間隔をLong形式で指定します。
pingInterval
Pingの間隔をDuration形式で指定します。

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

kotlin
import io.ktor.client.engine.okhttp.OkHttp

val client = HttpClient(OkHttp) {
    engine {
        preconfigured = OkHttpClient.Builder()
            .pingInterval(20, TimeUnit.SECONDS)
            .build()
    }
}

次の例では、Pingフレームを自動的に送信してWebSocket接続を維持するために、WebSocketsプラグインが20秒(20_000ミリ秒)のPing間隔で設定されています。

kotlin
val client = HttpClient(CIO) {
    install(WebSockets) {
        pingIntervalMillis = 20_000
    }
}

WebSocketセッションの操作

クライアントのWebSocketセッションは、DefaultClientWebSocketSessionインターフェースによって表されます。このインターフェースは、WebSocketフレームの送受信やセッションのクローズを行うためのAPIを提供します。

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

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

  • webSocket()関数は、ブロック引数としてDefaultClientWebSocketSessionを受け取ります。

    kotlin
    runBlocking {
        client.webSocket(
            method = HttpMethod.Get,
            host = "127.0.0.1",
            port = 8080,
            path = "/echo"
        ) {
            // this: 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エンドポイントを作成し、サーバーとの間でメッセージを送受信する方法を示します。

kotlin
package com.example

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.websocket.*
import io.ktor.http.*
import io.ktor.websocket.*
import kotlinx.coroutines.*
import java.util.*

fun main() {
    val client = HttpClient(CIO) {
        install(WebSockets) {
            pingIntervalMillis = 20_000
        }
    }
    runBlocking {
        client.webSocket(method = HttpMethod.Get, host = "127.0.0.1", port = 8080, path = "/echo") {
            while(true) {
                val othersMessage = incoming.receive() as? Frame.Text
                println(othersMessage?.readText())
                val myMessage = Scanner(System.`in`).next()
                if(myMessage != null) {
                    send(myMessage)
                }
            }
        }
    }
    client.close()
}

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