カスタムクライアントプラグイン

コード例: client-custom-plugin

v2.2.0以降、Ktorはカスタムクライアントプラグインを作成するための新しいAPIを提供しています。一般的に、このAPIではパイプラインやフェーズなどのKtorの内部概念を理解する必要はありません。その代わりに、onRequestやonResponseなどの一連のハンドラーを使用して、リクエストとレスポンスの処理のさまざまなステージにアクセスできます。

最初のプラグインの作成とインストール

このセクションでは、各リクエストにカスタムヘッダーを追加する最初のプラグインを作成してインストールする方法を説明します。

プラグインを作成するには、createClientPlugin関数を呼び出し、引数としてプラグイン名を渡します。
kotlin
```
package com.example.plugins

import io.ktor.client.plugins.api.*

val CustomHeaderPlugin = createClientPlugin("CustomHeaderPlugin") {
    // プラグインの設定 ...
}
```
この関数は、プラグインのインストールに使用されるClientPluginインスタンスを返します。

各リクエストにカスタムヘッダーを追加するには、リクエストパラメータへのアクセスを提供するonRequestハンドラーを使用できます。

kotlin

package com.example.plugins

import io.ktor.client.plugins.api.*

val CustomHeaderPlugin = createClientPlugin("CustomHeaderPlugin") {
    onRequest { request, _ ->
        request.headers.append("X-Custom-Header", "Default value")
    }
}

プラグインをインストールするには、作成したClientPluginインスタンスをクライアントの設定ブロック内のinstall関数に渡します。
kotlin
```
import com.example.plugins.*

val client = HttpClient(CIO) {
    install(CustomHeaderPlugin)
}
```

完全な例はこちらにあります: CustomHeader.kt。以降のセクションでは、プラグイン設定を提供する方法と、リクエストおよびレスポンスを処理する方法について詳しく説明します。

プラグイン設定の提供

前のセクションでは、各レスポンスにあらかじめ定義されたカスタムヘッダーを追加するプラグインの作成方法を示しました。このプラグインをより便利にするために、任意のカスタムヘッダー名と値を渡すための設定を提供してみましょう。

まず、設定クラスを定義する必要があります。

kotlin

class CustomHeaderPluginConfig {
    var headerName: String = "X-Custom-Header"
    var headerValue: String = "Default value"
}

プラグインでこの設定を使用するには、createClientPluginに設定クラスの参照を渡します。

kotlin

import io.ktor.client.plugins.api.*

val CustomHeaderConfigurablePlugin = createClientPlugin("CustomHeaderConfigurablePlugin", ::CustomHeaderPluginConfig) {
    val headerName = pluginConfig.headerName
    val headerValue = pluginConfig.headerValue

    onRequest { request, _ ->
        request.headers.append(headerName, headerValue)
    }
}

プラグインの設定フィールドは可変（mutable）であるため、ローカル変数に保存することをお勧めします。

最後に、次のようにプラグインをインストールして設定できます。

kotlin

val client = HttpClient(CIO) {
    install(CustomHeaderConfigurablePlugin) {
        headerName = "X-Custom-Header"
        headerValue = "Hello, world!"
    }
}

完全な例はこちらにあります: CustomHeaderConfigurable.kt。

リクエストとレスポンスの処理

カスタムプラグインは、専用のハンドラーセットを使用して、リクエストとレスポンスを処理するさまざまなステージへのアクセスを提供します。例えば：

onRequestとonResponseを使用すると、それぞれリクエストとレスポンスを処理できます。
transformRequestBodyとtransformResponseBodyを使用して、リクエストおよびレスポンスのボディに必要な変換を適用できます。

また、呼び出しの他のステージを処理するのに役立つ特定のフックを呼び出すことができるon(...)ハンドラーもあります。以下の表は、すべてのハンドラーを実行順に示しています。

基本的なフックすべてのフック

ハンドラー	説明
`onRequest`	このハンドラーは各HTTP リクエストリクエストの作成方法と、リクエストURL、HTTPメソッド、ヘッダー、リクエストボディなどのさまざまなリクエストパラメータの指定方法について学びます。に対して実行され、リクエストを修正できます。例: カスタムヘッダー
`transformRequestBody`	リクエストボディを変換できます。このハンドラーでは、ボディを OutgoingContent （例: `TextContent`、`ByteArrayContent`、`FormDataContent`）にシリアライズするか、変換が適用されない場合は`null`を返す必要があります。例: データ変換
`onResponse`	このハンドラーは、着信する各HTTP レスポンスリクエストの作成方法と、リクエストURL、HTTPメソッド、ヘッダー、リクエストボディなどのさまざまなリクエストパラメータの指定方法について学びます。に対して実行され、レスポンスのログ記録、クッキーの保存など、さまざまな方法でレスポンスを検査できます。例: ヘッダーのログ記録、レスポンス時間
`transformResponseBody`	レスポンスボディを変換できます。このハンドラーは、`HttpResponse.body`が呼び出されるたびに呼び出されます。ボディを`requestedType`のインスタンスにデシリアライズするか、変換が適用されない場合は`null`を返す必要があります。例: データ変換
`onClose`	このプラグインによって割り当てられたリソースをクリーンアップできます。このハンドラーは、クライアントがクローズされたときに呼び出されます。

ハンドラー	説明
`on(SetupRequest)`	`SetupRequest`フックは、リクエスト処理で最初に実行されます。
`onRequest`	このハンドラーは各HTTP リクエストリクエストの作成方法と、リクエストURL、HTTPメソッド、ヘッダー、リクエストボディなどのさまざまなリクエストパラメータの指定方法について学びます。に対して実行され、リクエストを修正できます。例: カスタムヘッダー
`transformRequestBody`	リクエストボディを変換できます。このハンドラーでは、ボディを OutgoingContent （例: `TextContent`、`ByteArrayContent`、`FormDataContent`）にシリアライズするか、変換が適用されない場合は`null`を返す必要があります。例: データ変換
`on(Send)`	`Send`フックは、レスポンスを検査し、必要に応じて追加のリクエストを開始する機能を提供します。これは、リダイレクトの処理、リクエストの再試行、認証などに役立ちます。例: 認証
`on(SendingRequest)`	`SendingRequest`フックは、ユーザーによって開始されたものでなくても、すべてのリクエストに対して実行されます。たとえば、リクエストによってリダイレクトが発生した場合、`onRequest`ハンドラーは元のリクエストに対してのみ実行されますが、`on(SendingRequest)`は元のリクエストとリダイレクトされたリクエストの両方に対して実行されます。同様に、`on(Send)`を使用して追加のリクエストを開始した場合、ハンドラーは次のように順序付けられます。 Console 例: ヘッダーのログ記録、レスポンス時間
`onResponse`	このハンドラーは、着信する各HTTP レスポンスリクエストの作成方法と、リクエストURL、HTTPメソッド、ヘッダー、リクエストボディなどのさまざまなリクエストパラメータの指定方法について学びます。に対して実行され、レスポンスのログ記録、クッキーの保存など、さまざまな方法でレスポンスを検査できます。例: ヘッダーのログ記録、レスポンス時間
`transformResponseBody`	レスポンスボディを変換できます。このハンドラーは、`HttpResponse.body`が呼び出されるたびに呼び出されます。ボディを`requestedType`のインスタンスにデシリアライズするか、変換が適用されない場合は`null`を返す必要があります。例: データ変換
`onClose`	このプラグインによって割り当てられたリソースをクリーンアップできます。このハンドラーは、クライアントがクローズされたときに呼び出されます。

呼び出し状態の共有

カスタムプラグインを使用すると、呼び出しに関連する任意の値を共有できるため、その呼び出しを処理する任意のハンドラー内でこの値にアクセスできます。この値は、call.attributesコレクション内の一意のキーを持つ属性として保存されます。以下の例では、属性を使用してリクエストの送信からレスポンスの受信までの時間を計算する方法を示します。

kotlin

import io.ktor.client.plugins.api.*
import io.ktor.util.*

val ResponseTimePlugin = createClientPlugin("ResponseTimePlugin") {
    val onCallTimeKey = AttributeKey<Long>("onCallTimeKey")
    on(SendingRequest) { request, content ->
        val onCallTime = System.currentTimeMillis()
        request.attributes.put(onCallTimeKey, onCallTime)
    }

    onResponse { response ->
        val onCallTime = response.call.attributes[onCallTimeKey]
        val onCallReceiveTime = System.currentTimeMillis()
        println("Read response delay (ms): ${onCallReceiveTime - onCallTime}")
    }
}

完全な例はこちらにあります: ResponseTime.kt。

クライアント設定へのアクセス

HttpClientインスタンスを返すclientプロパティを使用して、クライアント設定にアクセスできます。以下の例は、クライアントで使用されるプロキシアドレスを取得する方法を示しています。

kotlin

import io.ktor.client.plugins.api.*

val SimplePlugin = createClientPlugin("SimplePlugin") {
    val proxyAddress = client.engineConfig.proxy?.address()
    println("Proxy address: $proxyAddress")
}

例

以下のコードサンプルは、カスタムプラグインのいくつかの例を示しています。結果のプロジェクトはこちらにあります: client-custom-plugin。

カスタムヘッダー

各リクエストにカスタムヘッダーを追加するプラグインの作成方法を示します。

kotlin

package com.example.plugins

import io.ktor.client.plugins.api.*

val CustomHeaderConfigurablePlugin = createClientPlugin("CustomHeaderConfigurablePlugin", ::CustomHeaderPluginConfig) {
    val headerName = pluginConfig.headerName
    val headerValue = pluginConfig.headerValue

    onRequest { request, _ ->
        request.headers.append(headerName, headerValue)
    }
}

class CustomHeaderPluginConfig {
    var headerName: String = "X-Custom-Header"
    var headerValue: String = "Default value"
}

ヘッダーのログ記録

リクエストとレスポンスのヘッダーをログに記録するプラグインの作成方法を示します。

kotlin

package com.example.plugins

import io.ktor.client.plugins.api.*

val LoggingHeadersPlugin = createClientPlugin("LoggingHeadersPlugin") {
    on(SendingRequest) { request, content ->
        println("Request headers:")
        request.headers.entries().forEach { entry ->
            printHeader(entry)
        }
    }

    onResponse { response ->
        println("Response headers:")
        response.headers.entries().forEach { entry ->
            printHeader(entry)
        }
    }
}

private fun printHeader(entry: Map.Entry<String, List<String>>) {
    var headerString = entry.key + ": "
    entry.value.forEach { headerValue ->
        headerString += "${headerValue};"
    }
    println("-> $headerString")
}

レスポンス時間

リクエストの送信からレスポンスの受信までの時間を測定するプラグインの作成方法を示します。

kotlin

package com.example.plugins

import io.ktor.client.plugins.api.*
import io.ktor.util.*

val ResponseTimePlugin = createClientPlugin("ResponseTimePlugin") {
    val onCallTimeKey = AttributeKey<Long>("onCallTimeKey")
    on(SendingRequest) { request, content ->
        val onCallTime = System.currentTimeMillis()
        request.attributes.put(onCallTimeKey, onCallTime)
    }

    onResponse { response ->
        val onCallTime = response.call.attributes[onCallTimeKey]
        val onCallReceiveTime = System.currentTimeMillis()
        println("Read response delay (ms): ${onCallReceiveTime - onCallTime}")
    }
}

データ変換

transformRequestBodyフックとtransformResponseBodyフックを使用してリクエストおよびレスポンスのボディを変換する方法を示します。

DataTransformation.ktApplication.ktUser.kt

kotlin

package com.example.plugins

import com.example.model.*
import io.ktor.client.plugins.api.*
import io.ktor.http.*
import io.ktor.http.content.*
import io.ktor.utils.io.*

val DataTransformationPlugin = createClientPlugin("DataTransformationPlugin") {
    transformRequestBody { request, content, bodyType ->
        if (bodyType?.type == User::class) {
            val user = content as User
            TextContent(text="${user.name};${user.age}", contentType = ContentType.Text.Plain)
        } else {
            null
        }
    }
    transformResponseBody { response, content, requestedType ->
        if (requestedType.type == User::class) {
            val receivedContent = content.readUTF8Line()!!.split(";")
            User(receivedContent[0], receivedContent[1].toInt())
        } else {
            content
        }
    }
}

kotlin

package com.example

import com.example.model.*
import com.example.plugins.*
import com.example.server.*
import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.engine.cio.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import kotlinx.coroutines.*

fun main() {
    startServer()
    runBlocking {
        val client = HttpClient(CIO) {
            install(DataTransformationPlugin)
        }
        val bodyAsText = client.post("http://0.0.0.0:8080/post-data") {
            setBody(User("John", 42))
        }.bodyAsText()
        val user = client.get("http://0.0.0.0:8080/get-data").body<User>()
        println("Userinfo: $bodyAsText")
        println("Username: ${user.name}, age: ${user.age}")
    }
}

kotlin

package com.example.model

data class User(val name: String, val age: Int)

完全な例はこちらにあります: client-custom-plugin-data-transformation。

認証

サーバーから未認可（Unauthorized）のレスポンスを受信した場合に、on(Send)フックを使用してAuthorizationヘッダーにベアラートークンを追加する方法を示すサンプルKtorプロジェクトです。

Auth.ktApplication.kt

kotlin

package com.example.plugins

import io.ktor.client.plugins.api.*
import io.ktor.http.*

val AuthPlugin = createClientPlugin("AuthPlugin", ::AuthPluginConfig) {
    val token = pluginConfig.token

    on(Send) { request ->
        val originalCall = proceed(request)
        originalCall.response.run { // this: HttpResponse
            if(status == HttpStatusCode.Unauthorized && headers["WWW-Authenticate"]!!.contains("Bearer")) {
                request.headers.append("Authorization", "Bearer $token")
                proceed(request)
            } else {
                originalCall
            }
        }
    }
}

class AuthPluginConfig {
    var token: String = ""
}

kotlin

package com.example

import com.example.plugins.*
import com.example.server.*
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import kotlinx.coroutines.*

fun main() {
    startServer()
    runBlocking {
        val client = HttpClient(CIO) {
            install(AuthPlugin) {
                token = "abc123"
            }
        }
        val response = client.get("http://0.0.0.0:8080/")
        println(response.bodyAsText())
    }
}

完全な例はこちらにあります: client-custom-plugin-auth。

サーバーの作成と設定

依存関係の追加

依存性注入

ルーティング

リクエスト

レスポンス

コンテンツの提供

テンプレート

認証と認可

JSON Web Tokens

HTTP

WebSockets

モニタリング

管理

デプロイ

パッケージング

fat JARの作成

コンテナ化

公開

クライアントのセットアップ

リクエスト

レスポンス

認証と認可

WebSockets

モニタリング

カスタムクライアントプラグイン

最初のプラグインの作成とインストール

プラグイン設定の提供

リクエストとレスポンスの処理

呼び出し状態の共有

クライアント設定へのアクセス

例

カスタムヘッダー

ヘッダーのログ記録

レスポンス時間

データ変換

認証

依存関係の追加

依存性注入

テンプレート

認証と認可

JSON Web Tokens

WebSockets

fat JARの作成

認証と認可

WebSockets

カスタムクライアントプラグイン ​

最初のプラグインの作成とインストール ​

プラグイン設定の提供 ​

リクエストとレスポンスの処理 ​

呼び出し状態の共有 ​

クライアント設定へのアクセス ​

例 ​

カスタムヘッダー ​

ヘッダーのログ記録 ​

レスポンス時間 ​

データ変換 ​

認証 ​

カスタムクライアントプラグイン

最初のプラグインの作成とインストール

プラグイン設定の提供

リクエストとレスポンスの処理

呼び出し状態の共有

クライアント設定へのアクセス

例

カスタムヘッダー

ヘッダーのログ記録

レスポンス時間

データ変換

認証