Client Plugin

Ktor Client におけるコンテントネゴシエーションとシリアライズ

必要な依存関係: io.ktor:ktor-client-content-negotiation

コード例: client-json-kotlinx

ContentNegotiation プラグインは、主に 2 つの目的を果たします。

クライアントとサーバー間でのメディアタイプのネゴシエーション。これには、Accept および Content-Type ヘッダーを使用します。
リクエストの送信時やレスポンスの受信時に、特定のフォーマットでコンテンツをシリアライズ/デシリアライズすること。Ktor は、JSON、XML、CBOR、ProtoBuf のフォーマットを標準でサポートしています。

サーバー側では、Ktor はコンテンツをシリアライズ/デシリアライズするために ContentNegotiation プラグインを提供しています。

依存関係の追加

ContentNegotiation

ContentNegotiation を使用するには、ビルドスクリプトに ktor-client-content-negotiation アーティファクトを含める必要があります。

Gradle (Kotlin)Gradle (Groovy)Maven

Kotlin

Groovy

XML

TIP

Ktor クライアントに必要なアーティファクトの詳細については、を参照してください。

特定のフォーマットのシリアライザーには追加のアーティファクトが必要であることに注意してください。例えば、kotlinx.serialization の JSON には ktor-serialization-kotlinx-json 依存関係が必要です。含まれているアーティファクトに応じて、Ktor は自動的にデフォルトのシリアライザーを選択します。必要に応じて、シリアライザーを明示的に指定して設定することもできます。

Serialization

kotlinx.serialization コンバーターを使用する前に、Setup セクションの説明に従って Kotlin serialization プラグインを追加する必要があります。

JSON

JSON データをシリアライズ/デシリアライズするには、kotlinx.serialization、Gson、Jackson のいずれかのライブラリを選択できます。

XML

XML をシリアライズ/デシリアライズするには、ビルドスクリプトに ktor-serialization-kotlinx-xml を追加します。

Gradle (Kotlin)Gradle (Groovy)Maven

Kotlin

Groovy

XML

XML シリアライズは jsNode ターゲットではサポートされていないことに注意してください。

CBOR

CBOR をシリアライズ/デシリアライズするには、ビルドスクリプトに ktor-serialization-kotlinx-cbor を追加します。

Gradle (Kotlin)Gradle (Groovy)Maven

Kotlin

Groovy

XML

ProtoBuf

ProtoBuf をシリアライズ/デシリアライズするには、ビルドスクリプトに ktor-serialization-kotlinx-protobuf を追加します。

Gradle (Kotlin)Gradle (Groovy)Maven

Kotlin

Groovy

XML

ContentNegotiation のインストール

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

kotlin

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

これで、必要な JSON シリアライザーを設定できるようになります。

シリアライザーの設定

JSON シリアライザー

kotlinx.serializationGsonJackson

アプリケーションに JSON シリアライザーを登録するには、json メソッドを呼び出します。

kotlin

import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        json()
    }
}

json コンストラクタ内では、JsonBuilder API にアクセスできます。例：

kotlin

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        json(Json {
            prettyPrint = true
            isLenient = true
        })
    }
}

完全な例はこちらにあります: client-json-kotlinx。

アプリケーションに Gson シリアライザーを登録するには、gson メソッドを呼び出します。

kotlin

import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.gson.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        gson()
    }
}

gson メソッドでは、GsonBuilder によって提供されるシリアライズ設定を調整することもできます。

アプリケーションに Jackson シリアライザーを登録するには、jackson メソッドを呼び出します。

kotlin

import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.jackson.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        jackson()
    }
}

jackson メソッドでは、ObjectMapper によって提供されるシリアライズ設定を調整することもできます。例：

kotlin

import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.jackson.*
import com.fasterxml.jackson.databind.*
import java.text.DateFormat

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        jackson {
            enable(SerializationFeature.INDENT_OUTPUT)
            dateFormat = DateFormat.getDateInstance()
        }
    }
}

XML シリアライザー

アプリケーションに XML シリアライザーを登録するには、xml メソッドを呼び出します。

kotlin

import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.xml.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        xml()
    }
}

xml メソッドでは、XML シリアライズ設定にアクセスすることもできます。例：

kotlin

import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.xml.*
import nl.adaptivity.xmlutil.*
import nl.adaptivity.xmlutil.serialization.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        xml(format = XML {
            xmlDeclMode = XmlDeclMode.Charset
        })
    }
}

CBOR シリアライザー

アプリケーションに CBOR シリアライザーを登録するには、cbor メソッドを呼び出します。

kotlin

import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.cbor.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        cbor()
    }
}

cbor メソッドでは、CborBuilder によって提供される CBOR シリアライズ設定にアクセスすることもできます。例：

kotlin

import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.cbor.*
import kotlinx.serialization.cbor.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        cbor(Cbor {
            ignoreUnknownKeys = true
        })
    }
}

ProtoBuf シリアライザー

アプリケーションに ProtoBuf シリアライザーを登録するには、protobuf メソッドを呼び出します。

kotlin

import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.protobuf.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        protobuf()
    }
}

protobuf メソッドでは、ProtoBufBuilder によって提供される ProtoBuf シリアライズ設定にアクセスすることもできます。例：

kotlin

import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.protobuf.*
import kotlinx.serialization.protobuf.*

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        protobuf(ProtoBuf {
            encodeDefaults = true
        })
    }
}

データの受信と送信

データクラスの作成

データを送受信するには、データクラスが必要です。例：

kotlin

data class Customer(val id: Int, val firstName: String, val lastName: String)

kotlinx.serialization を使用する場合は、このクラスに @Serializable アノテーションが付いていることを確認してください。

kotlin

@Serializable
data class Customer(val id: Int, val firstName: String, val lastName: String)

以下の型のシリアライズ/デシリアライズは、kotlinx.serialization ライブラリによってサポートされています。

組み込みクラス (Builtin classes)
Sequence のデシリアライズ
Flow のシリアライズ

データの送信

リクエストボディ内でクラスインスタンスを JSON として送信するには、setBody 関数を使用してこのインスタンスを割り当て、contentType を呼び出してコンテンツタイプを application/json に設定します。

kotlin

val response: HttpResponse = client.post("http://localhost:8080/customer") {
    contentType(ContentType.Application.Json)
    setBody(Customer(3, "Jet", "Brains"))
}

データを XML または CBOR として送信するには、contentType をそれぞれ ContentType.Application.Xml または ContentType.Application.Cbor に設定します。

データの受信

サーバーが application/json、application/xml、または application/cbor コンテンツを含むレスポンスを送信した場合、レスポンスペイロードを受信するために使用する関数のパラメータとしてデータクラスを指定することで、それをデシリアライズできます（以下の例では body）。

kotlin

val customer: Customer = client.get("http://localhost:8080/customer/3").body()

完全な例はこちらにあります: client-json-kotlinx。

依存関係の追加

依存性注入

テンプレート

認証と認可

JSON Web Tokens

WebSockets

fat JARの作成

認証と認可

WebSockets

Ktor Client におけるコンテントネゴシエーションとシリアライズ

依存関係の追加 ​

ContentNegotiation ​

Serialization ​

JSON ​

XML ​

CBOR ​

ProtoBuf ​

ContentNegotiation のインストール ​

シリアライザーの設定 ​

JSON シリアライザー ​

XML シリアライザー ​

CBOR シリアライザー ​

ProtoBuf シリアライザー ​

データの受信と送信 ​

データクラスの作成 ​

データの送信 ​

データの受信 ​

依存関係の追加

ContentNegotiation

Serialization

JSON

XML

CBOR

ProtoBuf

ContentNegotiation のインストール

シリアライザーの設定

JSON シリアライザー

XML シリアライザー

CBOR シリアライザー

ProtoBuf シリアライザー

データの受信と送信

データクラスの作成

データの送信

データの受信