クライアントエンジン

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

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

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

Engine	Platforms
`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バージョンをサポートします。

Engine	Android version	Java version
`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
        customizeClient {
            // this: HttpAsyncClientBuilder
            setProxy(HttpHost("127.0.0.1", 8080))
            // ...
        }
        customizeRequest {
            // this: RequestConfig.Builder
        }
    }
}

Java

Javaエンジンは、Java 11で導入されたJava HTTPクライアントを使用します。これを使用するには、以下の手順に従います。

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

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エンジンを使用するには、以下の手順に従います。

libcurlライブラリをインストールします。
Linuxでは、libcurlのgnutlsバージョンをインストールする必要があります。 Ubuntuにこのバージョンをインストールするには、以下を実行します。
bash
```
sudo apt-get install libcurl4-gnutls-dev
```
Windowsでは、MinGW/MSYS2の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をサポートしているかどうかを示しています。

Engine	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/kmmktor/Platform.ktファイルを開き、構成ブロックを受け取りHttpClientを返すトップレベルのhttpClient()関数を追加します。
kotlin
```
expect fun httpClient(config: HttpClientConfig<*>.() -> Unit = {}): HttpClient
```

shared/src/androidMain/kotlin/com/example/kmmktor/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/kmmktor/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/kmmktor/Greeting.ktを開き、HttpClient()コンストラクターをhttpClient()関数呼び出しに置き換えます。
kotlin
```
private val client = httpClient()
```

依存関係の追加

テンプレート

認証と認可

JSON Webトークン

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

セキュリティ

プロキシのサポート

ロギング

タイムアウト

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