クライアントの設定

Estimated reading time: 1 minute

エンジンの選定と依存ライブラリの追加

クライアントを使用するためには、まずエンジンの選定と依存ライブラリの追加を行う必要があります。 Ktor はクライアント API を提供しており、実際の HTTP リクエスト処理はエンジンに移譲します。

各プラットフォームごとに、すぐに利用できるエンジンが多数用意されています。

マルチプラットフォーム の章により詳しく記載しています。

例えば、 CIO を使用する場合は下記を build.gradle に記載します。

dependencies {
    implementation("io.ktor:ktor-client-cio:$ktor_version")
}

クライアントの作成

クライアントを作成するには、下記のように書きます。

val client = HttpClient(CIO)

この CIO はエンジンクラスです。 どのエンジンクラスを使用すべきか迷った場合は、 CIO の使用を検討してください。

マルチプラットフォームの場合は、下記のようにエンジンの指定を省略することができます。

val client = HttpClient()

JVM ならば ServiceLoader を使用し、それ以外のプラットフォームでも同様のアプローチによって、 Ktor はアーティファクト内の利用可能なエンジンを自動的に選択し使用します。 依存ライブラリ内に複数のエンジンがある場合は、アルファベット順に解決します。

クライアントのインスタンスを複数作成しても、同一のクライアントを用いて複数のリクエストをしても、どちらでも問題ありません。

リソースの開放

Ktor クライアントは予めスレッド、 coroutine 、およびコネクションを確保します。 クライアントを利用し終わった後は、 close を呼びリソースを開放したくなると思います。

client.close()

1 リクエストごとにクライアントを生成する場合は、 use を使用することを検討してください。 use ブロックを抜けた際に、自動的にリソースを開放します。

val status = HttpClient().use { client ->
    ...
}

close メソッドは、新たなリクエストを停止するよう通知します。 これは非同期に実行され、現在実行中のリクエストが正常終了してからリソースを開放することができます。

また、 join メソッドですべてのリクエストが完了することを待ったり、 cancel メソッドでリクエストを停止することができます。

try {
    // close 後最大3秒待機
    withTimeout(3000) {
        client.close()
        client.join()
    }
} catch (timeout: TimeoutCancellationException) {
    // タイムアウト後に中止
    client.cancel()
}

Ktor の HttpClientCoroutineScope のライフサイクルに従います。 詳しくは Coroutines guide を参照してください。

クライアントの設定

クライアントのコンストラクタの関数パラメータでクライアントの設定を行うことができます。 クライアントは HttpClientEngineConfig で設定されます。

例えば threadCountプロキシ の設定は下記のように行います。

val client = HttpClient(CIO) {
    threadCount = 2
}

エンジン自体の設定を行う場合は、ブロック内で engine メソッドを呼びます。

val client = HttpClient(CIO) {
    engine {
        // エンジンの設定
    }
}

詳細は エンジン の章に記載されています。

次 : リクエストの準備.