クライアントエンジン

Ktor HTTP クライアントはマルチプラットフォームであり、JVM、Android、JavaScript（WebAssembly を含む）、および Native ターゲットで動作します。各プラットフォームでネットワークリクエストを処理するには、特定のエンジンが必要です。例えば、JVM アプリケーションには Apache や Jetty、Android には OkHttp や Android、Kotlin/Native をターゲットとするデスクトップアプリケーションには Curl を使用できます。エンジンごとに機能や設定がわずかに異なるため、プラットフォームやユースケースのニーズに最適なものを選択できます。

サポートされているプラットフォーム

以下の表は、各エンジンがサポートするプラットフォームの一覧です。

エンジン	プラットフォーム
`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-client-core アーティファクトに加えて、Ktor クライアントには特定のエンジンの依存関係が必要です。サポートされている各プラットフォームで利用可能なエンジンセットについては、対応するセクションで説明されています。

JVM
JVM および Android
JavaScript
Native

Ktor は、-jvm や -js などのサフィックスが付いたプラットフォーム固有のアーティファクトを提供しています。例えば、ktor-client-cio-jvm です。依存関係の解決方法はビルドツールによって異なります。Gradle は特定のプラットフォームに適したアーティファクトを解決しますが、Maven はこの機能をサポートしていません。つまり、Maven の場合はプラットフォームのサフィックスを手動で指定する必要があります。

エンジンの指定

特定のエンジンを使用するには、エンジンクラスを HttpClient コンストラクタに渡します。次の例では、CIO エンジンを使用してクライアントを作成します。

kotlin

import io.ktor.client.*
import io.ktor.client.engine.cio.*

val client = HttpClient(CIO)

デフォルトエンジン

エンジンの引数を省略した場合、クライアントはビルドスクリプト内の依存関係に基づいて自動的にエンジンを選択します。

kotlin

import io.ktor.client.*

val client = HttpClient()

これはマルチプラットフォームプロジェクトで特に便利です。例えば、Android と iOS の両方をターゲットとするプロジェクトの場合、androidMain ソースセットに Android の依存関係を、iosMain ソースセットに Darwin の依存関係を追加できます。HttpClient 作成時に、実行時に適切なエンジンが選択されます。

エンジンの設定

エンジンを設定するには、engine {} 関数を使用します。すべてのエンジンは、HttpClientEngineConfig の共通オプションを使用して設定できます。

kotlin

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 依存関係を追加します。
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

Apache5 クラスを引数として HttpClient コンストラクタに渡します。

kotlin

import io.ktor.client.*
import io.ktor.client.engine.apache5.*

val client = HttpClient(Apache5)

engine {} ブロックを使用して、Apache5EngineConfig のプロパティにアクセスし、設定します。

kotlin

import 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 依存関係を追加します。
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

Java クラスを引数として HttpClient コンストラクタに渡します。

kotlin

import io.ktor.client.*
import io.ktor.client.engine.java.*

val client = HttpClient(Java)

エンジンを設定するには、engine {} ブロックで JavaHttpConfig のプロパティを設定します。

kotlin

import 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 依存関係を追加します。
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

Jetty クラスを引数として HttpClient コンストラクタに渡します。

kotlin

import io.ktor.client.*
import io.ktor.client.engine.jetty.jakarta.*

val client = HttpClient(Jetty)

エンジンを設定するには、engine {} ブロックで JettyEngineConfig のプロパティを設定します。

kotlin

import 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 依存関係を追加します。
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

Android クラスを引数として HttpClient コンストラクタに渡します。

kotlin

import io.ktor.client.*
import io.ktor.client.engine.android.*

val client = HttpClient(Android)

エンジンを設定するには、engine {} ブロックで AndroidEngineConfig のプロパティを設定します。

kotlin

import 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 依存関係を追加します。
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

OkHttp クラスを引数として HttpClient コンストラクタに渡します。

kotlin

import io.ktor.client.*
import io.ktor.client.engine.okhttp.*

val client = HttpClient(OkHttp)

エンジンを設定するには、engine {} ブロックで OkHttpConfig のプロパティを設定します。

kotlin

import 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 依存関係を追加します。
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

Darwin クラスを引数として HttpClient コンストラクタに渡します。

kotlin

import io.ktor.client.*
import io.ktor.client.engine.darwin.*

val client = HttpClient(Darwin)

engine {} ブロックで DarwinClientEngineConfig を使用してエンジンを設定します。例えば、configureRequest でリクエストをカスタマイズしたり、configureSession でセッションをカスタマイズしたりできます。
kotlin
```
val client = HttpClient(Darwin) {
    engine {
        configureRequest {
            setAllowsCellularAccess(true)
        }
    }
}
```
完全な例については、client-engine-darwin を参照してください。

WinHttp

WinHttp エンジンは、Windows ベースのオペレーティングシステムをターゲットとしています。 WinHttp エンジンを使用するには、以下の手順に従ってください。

ktor-client-winhttp 依存関係を追加します。
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

WinHttp クラスを引数として HttpClient コンストラクタに渡します。

kotlin

import io.ktor.client.*
import io.ktor.client.engine.winhttp.*

val client = HttpClient(WinHttp)

engine {} ブロックで WinHttpClientEngineConfig を使用してエンジンを設定します。例えば、protocolVersion プロパティを使用して HTTP バージョンを変更できます。
kotlin
```
val client = HttpClient(WinHttp) {
    engine {
        protocolVersion = HttpProtocolVersion.HTTP_1_1
    }
}
```
完全な例については、client-engine-winhttp を参照してください。

Curl

デスクトッププラットフォーム向けに、Ktor は Curl エンジンを提供しています。これは linuxX64、linuxArm64、macosX64、macosArm64、および mingwX64 でサポートされています。Curl エンジンを使用するには、以下の手順に従ってください。

ktor-client-curl 依存関係を追加します。
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

Curl クラスを引数として HttpClient コンストラクタに渡します。

kotlin

import io.ktor.client.*
import io.ktor.client.engine.curl.*

val client = HttpClient(Curl)

engine {} ブロックで CurlClientEngineConfig を使用してエンジンを設定します。例えば、テスト目的で SSL 検証を無効にします。
kotlin
```
val 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 依存関係を追加します。
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML

CIO クラスを引数として HttpClient コンストラクタに渡します。

kotlin

import io.ktor.client.*
import io.ktor.client.engine.cio.*

val client = HttpClient(CIO)

engine {} ブロックで CIOEngineConfig を使用してエンジンを設定します。

kotlin

import 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)
        }
    }
}

JavaScript

Js エンジンは JavaScript プロジェクトで使用できます。ブラウザアプリケーションでは fetch API を、Node.js では node-fetch を使用します。これを使用するには、以下の手順に従ってください。

ktor-client-js 依存関係を追加します。
Gradle (Kotlin)Gradle (Groovy)Maven
Kotlin
Groovy
XML
Js クラスを引数として HttpClient コンストラクタに渡します。
kotlin
```
import io.ktor.client.*
import io.ktor.client.engine.js.*

val client = HttpClient(Js)
```
また、JsClient() 関数を呼び出して Js エンジンのシングルトンを取得することもできます。
kotlin
```
import io.ktor.client.engine.js.*

val client = JsClient()
```

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

制限事項

HTTP/2 および WebSockets

すべてのエンジンが HTTP/2 プロトコルをサポートしているわけではありません。エンジンが HTTP/2 をサポートしている場合は、エンジンの設定で有効にできます。例えば、Java エンジンなどです。

以下の表は、特定のエンジンが HTTP/2 および WebSockets をサポートしているかどうかを示しています。

エンジン	HTTP/2	WebSockets
`Apache5`	✅️	✖️
`Java`	✅	✅️
`Jetty`	✅	✖️
`CIO`	✖️	✅
`Android`	✖️	✖️
`OkHttp`	✅	✅
`Js`	✅	✅
`Darwin`	✅	✅
`WinHttp`	✅	✅
`Curl`	✅	✅

セキュリティ

SSL はエンジンごとに設定する必要があります。各エンジンは独自の SSL 設定オプションを提供しています。

プロキシのサポート

一部のエンジンはプロキシをサポートしていません。完全なリストについては、プロキシのドキュメントを参照してください。

ロギング

Logging プラグインは、ターゲットプラットフォームに応じてさまざまなロガータイプを提供します。

タイムアウト

HttpTimeout プラグインには、特定のエンジンでいくつかの制限があります。完全なリストについては、タイムアウトの制限事項を参照してください。

例：マルチプラットフォームモバイルプロジェクトでエンジンを設定する方法

マルチプラットフォームプロジェクトを構築する場合、expect と actual 宣言を使用して、ターゲットプラットフォームごとにエンジンを選択および設定できます。これにより、クライアント設定の大部分を共通コードで共有しながら、プラットフォームコードでエンジン固有のオプションを適用できます。ここでは、クロスプラットフォームモバイルアプリケーションの作成チュートリアルで作成したプロジェクトを使用して、これを実現する方法を示します。

shared/src/commonMain/kotlin/com/example/kmpktor/Platform.kt ファイルを開き、設定ブロックを受け取って HttpClient を返すトップレベルの httpClient() 関数を追加します。
kotlin
```
expect fun httpClient(config: HttpClientConfig<*>.() -> Unit = {}): HttpClient
```

shared/src/androidMain/kotlin/com/example/kmpktor/Platform.kt を開き、Android モジュール用の httpClient() 関数の actual 宣言を追加します。

kotlin

import 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 宣言を追加します。
kotlin
```
import 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() 関数の呼び出しに置き換えます。
kotlin
```
private val client = httpClient()
```

依存関係の追加

依存性注入

テンプレート

認証と認可

JSON Web Tokens

WebSockets

fat JARの作成

認証と認可

WebSockets

クライアントエンジン ​

サポートされているプラットフォーム ​

サポートされている Android/Java バージョン ​

エンジンの依存関係の追加 ​

エンジンの指定 ​

デフォルトエンジン ​

エンジンの設定 ​

JVM ​

Apache5 ​

Java ​

Jetty ​

JVM および Android ​

Android ​

OkHttp ​

Native ​

Darwin ​

WinHttp ​

Curl ​

JVM, Android, Native, JS および WasmJs ​

CIO ​

JavaScript ​

制限事項 ​

HTTP/2 および WebSockets ​

セキュリティ ​

プロキシのサポート ​

ロギング ​

タイムアウト ​

例：マルチプラットフォームモバイルプロジェクトでエンジンを設定する方法 ​

クライアントエンジン

サポートされているプラットフォーム

サポートされている Android/Java バージョン

エンジンの依存関係の追加

エンジンの指定

デフォルトエンジン

エンジンの設定

JVM

Apache5

Java

Jetty

JVM および Android

Android

OkHttp

Native

Darwin

WinHttp

Curl

JVM, Android, Native, JS および WasmJs

CIO

JavaScript

制限事項

HTTP/2 および WebSockets

セキュリティ

プロキシのサポート

ロギング

タイムアウト

例：マルチプラットフォームモバイルプロジェクトでエンジンを設定する方法