Skip to content

クライアントエンジン ​

Ktor HTTP クライアントはマルチプラットフォーム対応であり、JVM、Android、JavaScript(WebAssembly を含む)、および Native ターゲット上で動作します。ネットワークリクエストを処理するには、プラットフォームごとに固有のクライアントエンジンが必要です。

Ktor は、さまざまなプラットフォーム向けにいくつかのエンジンを提供しています。たとえば、JVM アプリケーションには Apache や Jetty、Android には OkHttp や Android、Kotlin/Native をターゲットとするデスクトップアプリケーションには Curl を使用できます。

各エンジンは、それぞれ異なる機能や設定オプションをサポートしています。マルチプラットフォームプロジェクトでは、Ktor のデフォルトエンジンを使用するか、個々のターゲット向けに特定のエンジンを選択できます。

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

以下の表は、各エンジンでサポートされているプラットフォームを示しています。

エンジンプラットフォーム
Apache5JVM
JavaJVM
JettyJVM
AndroidJVM, Android
OkHttpJVM, Android
DarwinNative
WinHttpNative
CurlNative
CIOJVM, Android, Native, JavaScript, WasmJs
JsJavaScript

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

JVM、または JVM と Android の両方をターゲットとするクライアントエンジンは、以下の Android/Java バージョンをサポートしています。

エンジンAndroid バージョンJava バージョン
Apache58+
Java11+
Jetty11+
CIO7.0+ *8+
Android1.x+8+
OkHttp5.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
kotlin {
    sourceSets {
        commonMain {
            dependencies {
                api("io.ktor:ktor-client-engine-defaults:3.6.1")
            }
        }
    }
}

エンジンを指定する ​

特定のエンジンを使用するには、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()

ターゲットプラットフォームで利用可能なエンジンが 1 つだけの場合、Ktor はそのエンジンを使用します。複数のエンジンが利用可能な場合、Ktor は最も優先度の高いエンジンを選択します。

デフォルトでは、CIO の優先度が最も低くなっています。これは、同じプラットフォームで CIO と別のサポートされているエンジンが利用可能な場合、Ktor はもう一方のエンジンを選択することを意味します。CIO は、より優先度の高いエンジンが利用できない場合に使用されます。

Kotlin Multiplatform プロジェクトでは、ktor-client-engine-defaults の依存関係が各ターゲットにデフォルトのエンジンを提供します。あるいは、対応するプラットフォームのソースセットに特定のエンジンの依存関係を追加することもできます。

エンジンを設定する ​

エンジンを設定するには、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 を使用してください。

  1. ktor-client-apache5 の依存関係を追加します。

    kotlin
    implementation(ktorLibs.client.apache5)
    上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
    groovy
    implementation ktorLibs.client.apache5
    上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-apache5-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. HttpClient コンストラクタの引数として Apache5 クラスを渡します。

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.apache5.*
    
    val client = HttpClient(Apache5)
  3. 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 を使用します。これを使用するには、以下の手順に従ってください。

  1. ktor-client-java の依存関係を追加します。

    kotlin
    implementation(ktorLibs.client.java)
    上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
    groovy
    implementation ktorLibs.client.java
    上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-java-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. HttpClient コンストラクタの引数として Java クラスを渡します。

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.java.*
    
    val client = HttpClient(Java)
  3. エンジンを設定するには、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 のみをサポートしており、次のように設定できます。

  1. ktor-client-jetty-jakarta の依存関係を追加します。

    kotlin
    implementation(ktorLibs.client.jetty)
    上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
    groovy
    implementation ktorLibs.client.jetty
    上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-jetty-jakarta-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. HttpClient コンストラクタの引数として Jetty クラスを渡します。

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.jetty.jakarta.*
    
    val client = HttpClient(Jetty)
  3. エンジンを設定するには、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 をターゲットとしており、次のように設定できます。

  1. ktor-client-android の依存関係を追加します。

    kotlin
    implementation(ktorLibs.client.android)
    上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
    groovy
    implementation ktorLibs.client.android
    上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-android-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. HttpClient コンストラクタの引数として Android クラスを渡します。

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.android.*
    
    val client = HttpClient(Android)
  3. エンジンを設定するには、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 をベースにしており、次のように設定できます。

  1. ktor-client-okhttp の依存関係を追加します。

    kotlin
    implementation(ktorLibs.client.okhttp)
    上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
    groovy
    implementation ktorLibs.client.okhttp
    上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-okhttp-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. HttpClient コンストラクタの引数として OkHttp クラスを渡します。

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.okhttp.*
    
    val client = HttpClient(OkHttp)
  3. エンジンを設定するには、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 エンジンを使用するには、以下の手順に従ってください。

  1. ktor-client-darwin の依存関係を追加します。

    kotlin
    implementation("io.ktor:ktor-client-darwin:$ktor_version")
    groovy
    implementation "io.ktor:ktor-client-darwin:$ktor_version"
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-darwin-macosx64</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. HttpClient コンストラクタの引数として Darwin クラスを渡します。

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.darwin.*
    
    val client = HttpClient(Darwin)
  3. engine {} ブロック内で DarwinClientEngineConfig を使用してエンジンを設定します。たとえば、configureRequest でリクエストをカスタマイズしたり、configureSession でセッションをカスタマイズしたりできます。

    kotlin
    val client = HttpClient(Darwin) {
        engine {
            configureRequest {
                setAllowsCellularAccess(true)
            }
        }
    }

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

WinHttp ​

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

  1. ktor-client-winhttp の依存関係を追加します。

    kotlin
    implementation("io.ktor:ktor-client-winhttp:$ktor_version")
    groovy
    implementation "io.ktor:ktor-client-winhttp:$ktor_version"
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-winhttp-mingwx64</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. HttpClient コンストラクタの引数として WinHttp クラスを渡します。

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.winhttp.*
    
    val client = HttpClient(WinHttp)
  3. 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 エンジンを使用するには、以下の手順に従ってください。

  1. ktor-client-curl の依存関係を追加します。

    kotlin
    implementation("io.ktor:ktor-client-curl:$ktor_version")
    groovy
    implementation "io.ktor:ktor-client-curl:$ktor_version"
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-curl-macosx64</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. HttpClient コンストラクタの引数として Curl クラスを渡します。

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.curl.*
    
    val client = HttpClient(Curl)
  3. 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 のみをサポートしています。これを使用するには、以下の手順に従ってください。

  1. ktor-client-cio の依存関係を追加します。

    kotlin
    implementation(ktorLibs.client.cio)
    上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
    groovy
    implementation ktorLibs.client.cio
    上記のスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-cio-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. HttpClient コンストラクタの引数として CIO クラスを渡します。

    kotlin
    import io.ktor.client.*
    import io.ktor.client.engine.cio.*
    
    val client = HttpClient(CIO)
  3. 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)
            }
            dnsResolver = CioDnsResolver(
                server = "1.1.1.1",
                timeout = 3.seconds
            )
        }
    }

JavaScript ​

Js エンジンは Kotlin/JS プロジェクトで使用できます。ブラウザアプリケーションでは Fetch API を、Node.js では node-fetch を使用します。

Js エンジンを使用するには、以下の手順に従ってください。

  1. ktor-client-js の依存関係を追加します。

    kotlin
    implementation("io.ktor:ktor-client-js:$ktor_version")
    groovy
    implementation "io.ktor:ktor-client-js:$ktor_version"
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-js-macosx64</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  2. HttpClient() コンストラクタの引数として Js クラスを渡します。

    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 を参照してください。

fetch のオーバーライド ​

デフォルトでは、Js エンジンはグローバルの fetch() 関数を使用します。カスタム実装を使用するには、エンジン設定で fetch プロパティを設定します。

kotlin
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/2WebSocket
Apache5✅️✖️
Java✅✅️
Jetty✅✖️
CIO✖️✅
Android✖️✖️
OkHttp✅✅
Js✅✅
Darwin✅✅
WinHttp✅✅
Curl✅✅

セキュリティ ​

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

プロキシのサポート ​

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

ロギング ​

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

タイムアウト ​

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

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

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

    1. shared/src/commonMain/kotlin/com/example/kmpktor/Platform.kt ファイルを開き、設定ブロックを受け取って HttpClient を返すトップレベルの httpClient() 関数を追加します。

      kotlin
      expect fun httpClient(config: HttpClientConfig<*>.() -> Unit = {}): HttpClient
    2. 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 でサポートされている他のエンジンを使用することもできます。

    3. 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() を呼び出すことができます。

    4. 共通コードでクライアントを使用するには、shared/src/commonMain/kotlin/com/example/kmpktor/Greeting.kt を開き、HttpClient() コンストラクタを httpClient() 関数の呼び出しに置き換えます。

      kotlin
      private val client = httpClient()