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 プラグインがすでにインストールされている場合は、次のいずれかの方法で既存の設定を置き換えることができます。

• defaultRequest() 関数の replace パラメーターを使用する：

val client = HttpClient(CIO) {
    defaultRequest(replace = true) {
        // this: DefaultRequestBuilder
    }
}

• ジェネリックな installOrReplace() 関数を使用する：

val client = HttpClient(CIO) {
    installOrReplace(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パスは末尾のスラッシュで終わる必要があります。そうしないと、RFC 3986のURL解決ルールに従って、リクエストパスがベースパスの最後のセグメントを置き換えてしまいます。たとえば、path("v1")はファイルとして扱われ、リクエストパスが追加されるときに削除されますが、path("v1/")はディレクトリのプレフィックスとして保持されます。

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ドメインソケットで構築することもできますが、ソケットパラメーターを使用してデフォルトリクエストを設定することも可能です。

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

val client = HttpClient(CIO)

// Unixドメインソケットへ単一のリクエストを送信する
val response: HttpResponse = client.get("/") {
    unixSocket("/tmp/test-unix-socket-ktor.sock")
}

// そのクライアントからのすべてのリクエストに対してソケットを設定する
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。