クライアントエンジン
Ktor HTTP クライアントはマルチプラットフォーム対応であり、JVM、Android、JavaScript(WebAssembly を含む)、および Native ターゲット上で動作します。ネットワークリクエストを処理するには、プラットフォームごとに固有のクライアントエンジンが必要です。
Ktor は、さまざまなプラットフォーム向けにいくつかのエンジンを提供しています。たとえば、JVM アプリケーションには Apache や Jetty、Android には OkHttp や Android、Kotlin/Native をターゲットとするデスクトップアプリケーションには Curl を使用できます。
各エンジンは、それぞれ異なる機能や設定オプションをサポートしています。マルチプラットフォームプロジェクトでは、Ktor のデフォルトエンジンを使用するか、個々のターゲット向けに特定のエンジンを選択できます。
サポートされているプラットフォーム
以下の表は、各エンジンでサポートされているプラットフォームを示しています。
| エンジン | プラットフォーム |
|---|---|
Apache5 | JVM |
Java | JVM |
Jetty | JVM |
Android | JVM, Android |
OkHttp | JVM, Android |
Darwin | Native |
WinHttp | Native |
Curl | Native |
CIO | JVM, Android, Native, JavaScript, WasmJs |
Js | JavaScript |
サポートされている Android/Java バージョン
JVM、または JVM と Android の両方をターゲットとするクライアントエンジンは、以下の Android/Java バージョンをサポートしています。
| エンジン | Android バージョン | Java バージョン |
|---|---|---|
Apache5 | 8+ | |
Java | 11+ | |
Jetty | 11+ | |
CIO | 7.0+ * | 8+ |
Android | 1.x+ | 8+ |
OkHttp | 5.0+ | 8+ |
* 古い Android バージョンで CIO エンジンを使用するには、Java 8 API の脱糖 (desugaring) を有効にする必要があります。
エンジンの依存関係を追加する
Ktor クライアントを使用するには、ktor-client-core アーティファクトに加えて、特定のエンジンの依存関係が必要です。
特定のエンジンの使用
サポートされている各プラットフォームには、利用可能なエンジンが用意されています。これらについては対応するセクションで説明しています。
Ktor は、-jvm や -js などのサフィックスが付いたプラットフォーム固有のアーティファクトを提供しています(例: ktor-client-cio-jvm)。 依存関係の解決方法はビルドツールによって異なります。Gradle は特定のプラットフォームに適したアーティファクトを自動的に解決しますが、Maven はこの機能をサポートしていません。つまり、Maven の場合はプラットフォームのサフィックスを手動で指定する必要があります。
マルチプラットフォームプロジェクトでデフォルトエンジンを使用する
ほとんどの Kotlin Multiplatform プロジェクトでは、ktor-client-engine-defaults アーティファクトを使用します。このアーティファクトは、ターゲットプラットフォームごとに精選されたクライアントエンジンを提供するため、プラットフォーム固有のソースセットで個別のエンジン依存関係を宣言する必要がなくなります。
commonMain ソースセットに ktor-client-engine-defaults アーティファクトを追加します。
kotlin {
sourceSets {
commonMain {
dependencies {
api("io.ktor:ktor-client-engine-defaults:3.6.1")
}
}
}
}エンジンを指定する
特定のエンジンを使用するには、HttpClient のコンストラクタにエンジンクラスを渡します。次の例では、CIO エンジンを使用してクライアントを作成します。
import io.ktor.client.*
import io.ktor.client.engine.cio.*
val client = HttpClient(CIO)エンジンの自動選択
エンジンの引数を省略した場合、クライアントはビルドスクリプト内で利用可能なエンジン依存関係の中から自動的にエンジンを選択します。
import io.ktor.client.*
val client = HttpClient()ターゲットプラットフォームで利用可能なエンジンが 1 つだけの場合、Ktor はそのエンジンを使用します。複数のエンジンが利用可能な場合、Ktor は最も優先度の高いエンジンを選択します。
デフォルトでは、CIO の優先度が最も低くなっています。これは、同じプラットフォームで CIO と別のサポートされているエンジンが利用可能な場合、Ktor はもう一方のエンジンを選択することを意味します。CIO は、より優先度の高いエンジンが利用できない場合に使用されます。
Kotlin Multiplatform プロジェクトでは、ktor-client-engine-defaults の依存関係が各ターゲットにデフォルトのエンジンを提供します。あるいは、対応するプラットフォームのソースセットに特定のエンジンの依存関係を追加することもできます。
エンジンを設定する
エンジンを設定するには、engine {} 関数を使用します。すべてのエンジンは、HttpClientEngineConfig にある共通オプションを使用して設定できます。
HttpClient() {
engine {
// this: HttpClientEngineConfig
threadsCount = 4
pipelining = true
}
}次のセクションでは、さまざまなプラットフォーム向けに特定のエンジンを設定する方法について説明します。
JVM
JVM ターゲットは、Apache5、Java、および Jetty エンジンをサポートしています。
Apache5
Apache5 エンジンは HTTP/1.1 と HTTP/2 の両方をサポートしており、デフォルトで HTTP/2 が有効になっています。 新規プロジェクトには、この Apache ベースのエンジンが推奨されます。
古い Apache エンジンは、非推奨となった Apache HttpClient 4 に依存しています。 これは後方互換性のためだけに残されています。すべての新規プロジェクトでは Apache5 を使用してください。
ktor-client-apache5の依存関係を追加します。kotlinimplementation(ktorLibs.client.apache5)上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。groovyimplementation ktorLibs.client.apache5上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-apache5-jvm</artifactId> <version>${ktor_version}</version> </dependency>HttpClientコンストラクタの引数としてApache5クラスを渡します。kotlinimport io.ktor.client.* import io.ktor.client.engine.apache5.* val client = HttpClient(Apache5)engine {}ブロックを使用して、Apache5EngineConfigのプロパティにアクセスして設定します。kotlinimport io.ktor.client.* import io.ktor.client.engine.apache5.* import org.apache.hc.core5.http.* val client = HttpClient(Apache5) { engine { // this: Apache5EngineConfig followRedirects = true socketTimeout = 10_000 connectTimeout = 10_000 connectionRequestTimeout = 20_000 // Apache5 の ConnectionManager を設定 configureConnectionManager { setMaxConnPerRoute(1_000) setMaxConnTotal(2_000) } // その他の設定のために基盤となる Apache クライアントをカスタマイズ customizeClient { // this: HttpAsyncClientBuilder setProxy(HttpHost("127.0.0.1", 8080)) // ... } // リクエストごとの設定をカスタマイズ customizeRequest { // this: RequestConfig.Builder } } }- 最大接続数などの接続マネージャーの設定には、
configureConnectionManagerを使用してください。これにより、Ktor が管理するエンジンの動作が保持されます。 - プロキシ、インターセプター、ロギングなど、接続マネージャーに関連しない設定にのみ
customizeClientを使用してください。
- 最大接続数などの接続マネージャーの設定には、
Java
Java エンジンは、Java 11 で導入された Java HTTP Client を使用します。これを使用するには、以下の手順に従ってください。
ktor-client-javaの依存関係を追加します。kotlinimplementation(ktorLibs.client.java)上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。groovyimplementation ktorLibs.client.java上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-java-jvm</artifactId> <version>${ktor_version}</version> </dependency>HttpClientコンストラクタの引数として Java クラスを渡します。kotlinimport io.ktor.client.* import io.ktor.client.engine.java.* val client = HttpClient(Java)エンジンを設定するには、
engine {}ブロック内でJavaHttpConfigのプロパティを設定します。kotlinimport io.ktor.client.* import io.ktor.client.engine.* import io.ktor.client.engine.java.* val client = HttpClient(Java) { engine { // this: JavaHttpConfig threadsCount = 8 pipelining = true proxy = ProxyBuilder.http("http://proxy-server.com/") protocolVersion = java.net.http.HttpClient.Version.HTTP_2 } }
Jetty
Jetty エンジンは HTTP/2 のみをサポートしており、次のように設定できます。
ktor-client-jetty-jakartaの依存関係を追加します。kotlinimplementation(ktorLibs.client.jetty)上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。groovyimplementation ktorLibs.client.jetty上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-jetty-jakarta-jvm</artifactId> <version>${ktor_version}</version> </dependency>HttpClientコンストラクタの引数としてJettyクラスを渡します。kotlinimport io.ktor.client.* import io.ktor.client.engine.jetty.jakarta.* val client = HttpClient(Jetty)エンジンを設定するには、
engine {}ブロック内でJettyEngineConfigのプロパティを設定します。kotlinimport io.ktor.client.* import io.ktor.client.engine.jetty.jakarta.* import org.eclipse.jetty.util.ssl.SslContextFactory val client = HttpClient(Jetty) { engine { // this: JettyEngineConfig sslContextFactory = SslContextFactory.Client() clientCacheSize = 12 } }
JVM と Android
このセクションでは、JVM/Android で利用可能なエンジンとその設定について説明します。
Android
Android エンジンは Android をターゲットとしており、次のように設定できます。
ktor-client-androidの依存関係を追加します。kotlinimplementation(ktorLibs.client.android)上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。groovyimplementation ktorLibs.client.android上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-android-jvm</artifactId> <version>${ktor_version}</version> </dependency>HttpClientコンストラクタの引数としてAndroidクラスを渡します。kotlinimport io.ktor.client.* import io.ktor.client.engine.android.* val client = HttpClient(Android)エンジンを設定するには、
engine {}ブロック内でAndroidEngineConfigのプロパティを設定します。kotlinimport io.ktor.client.* import io.ktor.client.engine.android.* import java.net.Proxy import java.net.InetSocketAddress val client = HttpClient(Android) { engine { // this: AndroidEngineConfig connectTimeout = 100_000 socketTimeout = 100_000 proxy = Proxy(Proxy.Type.HTTP, InetSocketAddress("localhost", 8080)) } }
OkHttp
OkHttp エンジンは OkHttp をベースにしており、次のように設定できます。
ktor-client-okhttpの依存関係を追加します。kotlinimplementation(ktorLibs.client.okhttp)上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。groovyimplementation ktorLibs.client.okhttp上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-okhttp-jvm</artifactId> <version>${ktor_version}</version> </dependency>HttpClientコンストラクタの引数としてOkHttpクラスを渡します。kotlinimport io.ktor.client.* import io.ktor.client.engine.okhttp.* val client = HttpClient(OkHttp)エンジンを設定するには、
engine {}ブロック内でOkHttpConfigのプロパティを設定します。kotlinimport io.ktor.client.* import io.ktor.client.engine.okhttp.* val client = HttpClient(OkHttp) { engine { // this: OkHttpConfig config { // this: OkHttpClient.Builder followRedirects(true) // ... } addInterceptor(interceptor) addNetworkInterceptor(interceptor) preconfigured = okHttpClientInstance duplexStreamingEnabled = true // HTTP/2 接続でのみ利用可能 } }
Native
Ktor は、Kotlin/Native ターゲット向けに Darwin、WinHttp、および Curl エンジンを提供しています。
Kotlin/Native プロジェクトで Ktor を使用するには、新しいメモリマネージャーが必要です。これは Kotlin 1.7.20 以降でデフォルトで有効になっています。
Darwin
Darwin エンジンは、macOS、iOS、tvOS、watchOS などの Darwin ベースのオペレーティングシステムをターゲットとしています。内部で NSURLSession を使用します。Darwin エンジンを使用するには、以下の手順に従ってください。
ktor-client-darwinの依存関係を追加します。kotlinimplementation("io.ktor:ktor-client-darwin:$ktor_version")groovyimplementation "io.ktor:ktor-client-darwin:$ktor_version"xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-darwin-macosx64</artifactId> <version>${ktor_version}</version> </dependency>HttpClientコンストラクタの引数としてDarwinクラスを渡します。kotlinimport io.ktor.client.* import io.ktor.client.engine.darwin.* val client = HttpClient(Darwin)engine {}ブロック内でDarwinClientEngineConfigを使用してエンジンを設定します。たとえば、configureRequestでリクエストをカスタマイズしたり、configureSessionでセッションをカスタマイズしたりできます。kotlinval client = HttpClient(Darwin) { engine { configureRequest { setAllowsCellularAccess(true) } } }完全な例については、client-engine-darwin を参照してください。
WinHttp
WinHttp エンジンは Windows ベースのオペレーティングシステムをターゲットとしています。 WinHttp エンジンを使用するには、以下の手順に従ってください。
ktor-client-winhttpの依存関係を追加します。kotlinimplementation("io.ktor:ktor-client-winhttp:$ktor_version")groovyimplementation "io.ktor:ktor-client-winhttp:$ktor_version"xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-winhttp-mingwx64</artifactId> <version>${ktor_version}</version> </dependency>HttpClientコンストラクタの引数としてWinHttpクラスを渡します。kotlinimport io.ktor.client.* import io.ktor.client.engine.winhttp.* val client = HttpClient(WinHttp)engine {}ブロック内でWinHttpClientEngineConfigを使用してエンジンを設定します。たとえば、protocolVersionプロパティを使用して HTTP バージョンを変更できます。kotlinval client = HttpClient(WinHttp) { engine { protocolVersion = HttpProtocolVersion.HTTP_1_1 } }完全な例については、client-engine-winhttp を参照してください。
Curl
デスクトッププラットフォーム向けに、Ktor は Curl エンジンを提供しています。これは linuxX64、linuxArm64、macosX64、macosArm64、および mingwX64 でサポートされています。Curl エンジンを使用するには、以下の手順に従ってください。
ktor-client-curlの依存関係を追加します。kotlinimplementation("io.ktor:ktor-client-curl:$ktor_version")groovyimplementation "io.ktor:ktor-client-curl:$ktor_version"xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-curl-macosx64</artifactId> <version>${ktor_version}</version> </dependency>HttpClientコンストラクタの引数としてCurlクラスを渡します。kotlinimport io.ktor.client.* import io.ktor.client.engine.curl.* val client = HttpClient(Curl)engine {}ブロック内でCurlClientEngineConfigを使用してエンジンを設定します。たとえば、テスト目的で SSL 検証を無効にすることができます。kotlinval client = HttpClient(Curl) { engine { sslVerify = false } }完全な例については、client-engine-curl を参照してください。
JVM、Android、Native、JS および WasmJs
CIO
CIO エンジンは、JVM、Android、Native、JavaScript、および WebAssembly JavaScript (WasmJs) プラットフォームで利用可能な、完全に非同期なコルーチンベースのエンジンです。現在は HTTP/1.x のみをサポートしています。これを使用するには、以下の手順に従ってください。
ktor-client-cioの依存関係を追加します。kotlinimplementation(ktorLibs.client.cio)上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。groovyimplementation ktorLibs.client.cio上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-cio-jvm</artifactId> <version>${ktor_version}</version> </dependency>HttpClientコンストラクタの引数としてCIOクラスを渡します。kotlinimport io.ktor.client.* import io.ktor.client.engine.cio.* val client = HttpClient(CIO)engine {}ブロック内でCIOEngineConfigを使用してエンジンを設定します。kotlinimport io.ktor.client.* import io.ktor.client.engine.cio.* import io.ktor.network.tls.* val client = HttpClient(CIO) { engine { // this: CIOEngineConfig maxConnectionsCount = 1000 endpoint { // this: EndpointConfig maxConnectionsPerRoute = 100 pipelineMaxSize = 20 keepAliveTime = 5000 connectTimeout = 5000 connectAttempts = 5 } https { // this: TLSConfigBuilder serverName = "api.ktor.io" cipherSuites = CIOCipherSuites.SupportedSuites trustManager = myCustomTrustManager random = mySecureRandom addKeyStore(myKeyStore, myKeyStorePassword) } dnsResolver = CioDnsResolver( server = "1.1.1.1", timeout = 3.seconds ) } }
JavaScript
Js エンジンは Kotlin/JS プロジェクトで使用できます。ブラウザアプリケーションでは Fetch API を、Node.js では node-fetch を使用します。
Js エンジンを使用するには、以下の手順に従ってください。
ktor-client-jsの依存関係を追加します。kotlinimplementation("io.ktor:ktor-client-js:$ktor_version")groovyimplementation "io.ktor:ktor-client-js:$ktor_version"xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-js-macosx64</artifactId> <version>${ktor_version}</version> </dependency>HttpClient()コンストラクタの引数としてJsクラスを渡します。kotlinimport io.ktor.client.* import io.ktor.client.engine.js.* val client = HttpClient(Js)あるいは、
JsClient()関数を呼び出してJsエンジンのシングルトンを取得することもできます。kotlinimport io.ktor.client.engine.js.* val client = JsClient()完全な例については、client-engine-js を参照してください。
fetch のオーバーライド
デフォルトでは、Js エンジンはグローバルの fetch() 関数を使用します。カスタム実装を使用するには、エンジン設定で fetch プロパティを設定します。
val client = HttpClient(Js) {
engine {
fetch = { url, init ->
Promise.reject(IllegalStateException("Networking not available"))
}
}
}これは、独自の fetch() 実装やラッパーを提供する JavaScript ライブラリと統合する場合に役立ちます。
制限事項
HTTP/2 と WebSocket
すべてのエンジンが HTTP/2 プロトコルをサポートしているわけではありません。エンジンが HTTP/2 をサポートしている場合は、エンジンの設定で有効にすることができます(例: Java エンジン)。
以下の表は、特定のエンジンが HTTP/2 および WebSocket をサポートしているかどうかを示しています。
| エンジン | HTTP/2 | WebSocket |
|---|---|---|
Apache5 | ✅️ | ✖️ |
Java | ✅ | ✅️ |
Jetty | ✅ | ✖️ |
CIO | ✖️ | ✅ |
Android | ✖️ | ✖️ |
OkHttp | ✅ | ✅ |
Js | ✅ | ✅ |
Darwin | ✅ | ✅ |
WinHttp | ✅ | ✅ |
Curl | ✅ | ✅ |
セキュリティ
SSL はエンジンごとに設定する必要があります。各エンジンが独自の SSL 設定オプションを提供しています。
プロキシのサポート
一部のエンジンはプロキシをサポートしていません。完全なリストについては、プロキシに関するドキュメントを参照してください。
ロギング
Logging プラグインは、ターゲットプラットフォームに応じて異なるロガータイプを提供します。
タイムアウト
HttpTimeout プラグインには、特定のエンジンにおいていくつかの制限事項があります。完全なリストについては、タイムアウトの制限事項を参照してください。
例: マルチプラットフォームモバイルプロジェクトでエンジンを設定する方法
マルチプラットフォームプロジェクトを構築する場合、expected / actual 宣言を使用して、各ターゲットプラットフォームのエンジンを選択および設定できます。これにより、クライアントの共通設定の大半を共通コードで共有しながら、プラットフォーム固有のコードでエンジン固有のオプションを適用できます。 ここでは、「クロスプラットフォームモバイルアプリケーションの作成」チュートリアルで作成したプロジェクトを使用して、これを実現する方法を示します。
shared/src/commonMain/kotlin/com/example/kmpktor/Platform.kt ファイルを開き、設定ブロックを受け取って
HttpClientを返すトップレベルのhttpClient()関数を追加します。kotlinexpect fun httpClient(config: HttpClientConfig<*>.() -> Unit = {}): HttpClientshared/src/androidMain/kotlin/com/example/kmpktor/Platform.kt を開き、Android モジュール用の
httpClient()関数の actual 宣言を追加します。kotlinimport io.ktor.client.* import io.ktor.client.engine.okhttp.* import java.util.concurrent.TimeUnit actual fun httpClient(config: HttpClientConfig<*>.() -> Unit) = HttpClient(OkHttp) { config(this) engine { config { retryOnConnectionFailure(true) connectTimeout(0, TimeUnit.SECONDS) } } }この例では
OkHttpエンジンの設定方法を示していますが、Android でサポートされている他のエンジンを使用することもできます。shared/src/iosMain/kotlin/com/example/kmpktor/Platform.kt を開き、iOS モジュール用の
httpClient()関数の actual 宣言を追加します。kotlinimport io.ktor.client.* import io.ktor.client.engine.darwin.* actual fun httpClient(config: HttpClientConfig<*>.() -> Unit) = HttpClient(Darwin) { config(this) engine { configureRequest { setAllowsCellularAccess(true) } } }これで、どのエンジンが使用されているかを意識することなく、共通コード内で
httpClient()を呼び出すことができます。共通コードでクライアントを使用するには、shared/src/commonMain/kotlin/com/example/kmpktor/Greeting.kt を開き、
HttpClient()コンストラクタをhttpClient()関数の呼び出しに置き換えます。kotlinprivate val client = httpClient()
