クライアントの作成と設定

クライアントの依存関係を追加したら、HttpClientクラスのインスタンスを作成し、エンジンをパラメータとして渡すことで、クライアントをインスタンス化できます。

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

val client = HttpClient(CIO)

この例では、CIOエンジンを使用しています。 エンジンを省略することもできます。

import io.ktor.client.*

val client = HttpClient()

この場合、クライアントはビルドスクリプトに追加されたアーティファクトに応じて、エンジンを自動的に選択します。クライアントがどのようにエンジンを選択するかは、デフォルトエンジンのドキュメントセクションで確認できます。

クライアントの構成

基本的な構成

クライアントを構成するには、クライアントコンストラクタに追加の関数型パラメータを渡すことができます。HttpClientConfigクラスは、クライアントを構成するためのベースクラスです。例えば、expectSuccessプロパティを使用してレスポンス検証を有効にできます。

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

val client = HttpClient(CIO) {
    expectSuccess = true
}

エンジン構成

engine関数を使用してエンジンを構成できます。

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

val client = HttpClient(CIO) {
    engine {
        // Configure an engine
    }
}

詳細については、エンジンセクションを参照してください。

プラグイン

プラグインをインストールするには、クライアント構成ブロック内でinstall関数に渡す必要があります。例えば、LoggingプラグインをインストールすることでHTTPコールをログに記録できます。

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

val client = HttpClient(CIO) {
    install(Logging)
}

installブロック内でプラグインを構成することもできます。例えば、Loggingプラグインの場合、ロガー、ログレベル、およびログメッセージをフィルタリングする条件を指定できます。

val client = HttpClient(CIO) {
    install(Logging) {
        logger = Logger.DEFAULT
        level = LogLevel.HEADERS
        filter { request ->
            request.url.host.contains("ktor.io")
        }
        sanitizeHeader { header -> header == HttpHeaders.Authorization }
    }
}

特定のプラグインには別途依存関係が必要な場合があることに注意してください。

クライアントの使用

必要なすべての依存関係を追加し、クライアントを作成したら、それを使用してリクエストを作成し、レスポンスを受信できます。

クライアントを閉じる

HTTPクライアントの操作が終了したら、リソース（スレッド、コネクション、コルーチン用のCoroutineScope）を解放する必要があります。これを行うには、HttpClient.close関数を呼び出します。

client.close()

close関数は新しいリクエストの作成を禁止しますが、現在アクティブなリクエストを終了させるわけではないことに注意してください。リソースは、すべてのクライアントリクエストが完了した後にのみ解放されます。

単一のリクエストでHttpClientを使用する必要がある場合は、コードブロックの実行後に自動的にcloseを呼び出すuse関数を呼び出します。

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

HttpClientの作成は安価な操作ではないため、複数のリクエストの場合はそのインスタンスを再利用する方が良いです。