Client Plugin

デフォルトリクエスト

コード例: client-default-request

DefaultRequest プラグインを使用すると、すべての リクエスト のデフォルトパラメーターを設定できます。ベース URL の指定、ヘッダーの追加、クエリパラメーターの設定などです。

依存関係の追加

DefaultRequest は ktor-client-core アーティファクトのみを必要とし、特定の依存関係は不要です。

DefaultRequest のインストール

DefaultRequest をインストールするには、クライアント設定ブロック 内の install 関数に渡します。

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.*
//...
val client = HttpClient(CIO) {
    install(DefaultRequest)
}

または、defaultRequest 関数を呼び出して、必要なリクエストパラメーターを 設定 します。

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.*
//...
val client = HttpClient(CIO) {
    defaultRequest {
        // this: DefaultRequestBuilder
    }
}

DefaultRequest の設定

ベース URL

DefaultRequest を使用すると、リクエスト URL とマージされる URL のベース部分を設定できます。たとえば、以下の url 関数は、すべてのリクエストのベース URL を指定します。

defaultRequest {
    url("https://ktor.io/docs/")
}

上記の構成のクライアントを使用して以下のリクエストを行うと、...

val response: HttpResponse = client.get("welcome.html")

... 結果の URL は https://ktor.io/docs/welcome.html になります。ベース URL とリクエスト URL がどのようにマージされるかについては、DefaultRequest を参照してください。

URL パラメーター

url 関数では、URL コンポーネントを個別に指定することもできます。例:

• HTTP スキーム;
• ホスト名;
• ベース URL パス;
• クエリパラメーター。

url {
    protocol = URLProtocol.HTTPS
    host = "ktor.io"
    path("docs/")
    parameters.append("token", "abc123")
}

ヘッダー

各リクエストに特定のヘッダーを追加するには、header 関数を使用します。

defaultRequest {
    header("X-Custom-Header", "Hello")
}

ヘッダーの重複を避けるために、appendIfNameAbsent、appendIfNameAndValueAbsent、および contains 関数を使用できます。

defaultRequest {
    headers.appendIfNameAbsent("X-Custom-Header", "Hello")
}

Unix ドメインソケット

Unix ドメインソケットは CIO エンジンでのみサポートされています。

Unix ドメインソケットで個々のリクエストを構築 できますが、ソケットパラメーターを使用してデフォルトリクエストを設定することもできます。

これを行うには、ソケットへのパスを含む unixSocket 呼び出しを defaultRequest 関数に渡します。例:

val client = HttpClient(CIO)

// Sending a single request to a Unix domain socket
val response: HttpResponse = client.get("/") {
    unixSocket("/tmp/test-unix-socket-ktor.sock")
}

// Setting up the socket for all requests from that client
val clientDefault = HttpClient(CIO) {
    defaultRequest {
        unixSocket("/tmp/test-unix-socket-ktor.sock")
    }    
}

val response: HttpResponse = clientDefault.get("/")

例

以下の例では、次の DefaultRequest 設定を使用します。

• url 関数は、HTTP スキーム、ホスト、ベース URL パス、およびクエリパラメーターを定義します。
• header 関数は、すべてのリクエストにカスタムヘッダーを追加します。

val client = HttpClient(CIO) {
    defaultRequest {
        url {
            protocol = URLProtocol.HTTPS
            host = "ktor.io"
            path("docs/")
            parameters.append("token", "abc123")
        }
        header("X-Custom-Header", "Hello")
    }
}

このクライアントによって行われる以下のリクエストは、後続のパスセグメントのみを指定し、DefaultRequest 用に設定されたパラメーターを自動的に適用します。

val response: HttpResponse = client.get("welcome.html")
println(response.status)

完全な例は、こちらで確認できます: client-default-request。