Ktor Client におけるコンテンツネゴシエーションとシリアライゼーション
必要な依存関係: io.ktor:ktor-client-content-negotiation
コード例: client-json-kotlinx
ContentNegotiation プラグインには、主に2つの目的があります。
AcceptおよびContent-Typeヘッダーを使用した、クライアントとサーバー間のメディアタイプのネゴシエーション。- サポートされている形式でのリクエストボディのシリアライズおよびレスポンスボディのデシリアライズ。Ktor は JSON、XML、CBOR、および ProtoBuf の組み込みサポートを提供しています。
サーバー側では、Ktor はコンテンツのシリアライズとデシリアライズのために ContentNegotiation プラグインを提供しています。
依存関係の追加
コンテンツネゴシエーション
ContentNegotiation を使用するには、ビルドスクリプトに ktor-client-content-negotiation アーティファクトを追加します。
implementation(ktorLibs.client.contentNegotiation)implementation ktorLibs.client.contentNegotiation<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-client-content-negotiation-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>特定の形式のシリアライザーには追加のアーティファクトが必要です。
例えば、kotlinx.serialization で JSON を扱うには ktor-serialization-kotlinx-json 依存関係が必要です。含まれているアーティファクトに応じて、Ktor はデフォルトのシリアライザーを自動的に選択します。必要に応じて、シリアライザーを明示的に指定して設定することもできます。
シリアライゼーション
kotlinx.serialization コンバーターを使用する前に、セットアップ (Setup) セクションの説明に従って Kotlin serialization プラグインを追加してください。
JSON
JSON データのシリアライズとデシリアライズを行うには、プロジェクトにシリアライゼーションライブラリを追加します。Ktor は kotlinx.serialization、Gson、または Jackson をサポートしています。
ビルドスクリプトに ktor-serialization-kotlinx-json アーティファクトを追加します。
implementation(ktorLibs.serialization.kotlinx.json)implementation ktorLibs.serialization.kotlinx.json<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-json-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>ビルドスクリプトに ktor-serialization-gson アーティファクトを追加します。
implementation(ktorLibs.serialization.gson)implementation ktorLibs.serialization.gson<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-gson-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>ビルドスクリプトに ktor-serialization-jackson アーティファクトを追加します。
implementation(ktorLibs.serialization.jackson)implementation ktorLibs.serialization.jackson<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-jackson-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>XML
XML のシリアライズとデシリアライズを行うには、ビルドスクリプトに ktor-serialization-kotlinx-xml アーティファクトを追加します。
implementation(ktorLibs.serialization.kotlinx.xml)implementation ktorLibs.serialization.kotlinx.xml<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-xml-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>CBOR
CBOR のシリアライズとデシリアライズを行うには、ビルドスクリプトに ktor-serialization-kotlinx-cbor アーティファクトを追加します。
implementation(ktorLibs.serialization.kotlinx.cbor)implementation ktorLibs.serialization.kotlinx.cbor<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-cbor-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>ProtoBuf
ProtoBuf のシリアライズとデシリアライズを行うには、ビルドスクリプトに ktor-serialization-kotlinx-protobuf アーティファクトを追加します。
implementation(ktorLibs.serialization.kotlinx.protobuf)implementation ktorLibs.serialization.kotlinx.protobuf<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-protobuf-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>ContentNegotiation のインストール
ContentNegotiation プラグインをインストールするには、クライアント設定ブロック で install 関数に渡します。
val client = HttpClient(CIO) {
install(ContentNegotiation)
}その後、必要な JSON シリアライザーを設定できます。
シリアライザーの設定
JSON シリアライザー
アプリケーションに JSON シリアライザーを登録するには、json() 関数を呼び出します。
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
json()
}
}JSON シリアライゼーションをカスタマイズするには、json() コンストラクターに Json 設定を渡します。
val client = HttpClient(CIO) {
install(ContentNegotiation) {
json(Json {
prettyPrint = true
isLenient = true
})
}
}利用可能な設定オプションについては、JsonBuilder を参照してください。
完全な例については、client-json-kotlinx を参照してください。
アプリケーションに Gson シリアライザーを登録するには、gson() 関数を呼び出します。
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.gson.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
gson()
}
}Gson シリアライゼーションをカスタマイズするには、gson() 関数に設定ブロックを渡します。利用可能な設定オプションについては、GsonBuilder を参照してください。
アプリケーションに Jackson シリアライザーを登録するには、jackson() 関数を呼び出します。
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.jackson.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
jackson()
}
}Jackson シリアライゼーションをカスタマイズするには、ObjectMapper が提供する設定を使用します。
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() 関数を呼び出します。
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.xml.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
xml()
}
}XML シリアライゼーションをカスタマイズするには、必要なオプションを xml() 関数に渡します。
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() 関数を呼び出します。
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.cbor.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
cbor()
}
}CBOR シリアライゼーションをカスタマイズするには、cbor() コンストラクターに Cbor 設定を渡します。
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
})
}
}利用可能な設定オプションについては、CborBuilder を参照してください。
ProtoBuf シリアライザー
アプリケーションに ProtoBuf シリアライザーを登録するには、protobuf() 関数を呼び出します。
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.protobuf.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
protobuf()
}
}ProtoBuf シリアライゼーションをカスタマイズするには、protobuf() 関数に ProtoBuf 設定を渡します。
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
})
}
}利用可能なオプションについては、ProtoBufBuilder を参照してください。
Accept ヘッダーの設定
デフォルトでは、ContentNegotiation プラグインは登録されたコンテンツタイプを送信リクエストの Accept ヘッダーに追加します。
Accept ヘッダーを明示的に設定しており、プラグインによって登録済みコンテンツタイプを追加したくない場合は、acceptHeaderMergeStrategy プロパティを ContentTypeMergeStrategy.SkipIfPresent に設定します。
val client = HttpClient(CIO) {
install(ContentNegotiation) {
register(ContentType.Application.Json, noOpJsonConverter)
acceptHeaderMergeStrategy = ContentTypeMergeStrategy.SkipIfPresent
}
}SkipIfPresent を使用すると、プラグインは既存の Accept ヘッダーを保持します。リクエストに Accept ヘッダーが含まれていない場合、プラグインは通常どおり登録されたコンテンツタイプを追加します。
データの送受信
データクラスの作成
以下の例では、クライアントが送受信するデータを表すために Customer データクラスを使用しています。
data class Customer(val id: Int, val firstName: String, val lastName: String)kotlinx.serialization を使用する場合は、クラスに @Serializable アノテーションを付加します。
@Serializable
data class Customer(val id: Int, val firstName: String, val lastName: String)kotlinx.serialization ライブラリでは、以下の型のシリアライズ/デシリアライズがサポートされています。
- 組み込みクラス (Builtin classes)
- Sequence のデシリアライズ
- Flow のシリアライズ
データの送信
リクエストボディでクラスのインスタンスを送信するには、setBody() 関数を使用してこのインスタンスを割り当て、contentType() 関数を使用してコンテンツタイプを設定します。
以下の例は、Customer オブジェクトを JSON として送信します。
val response: HttpResponse = client.post("http://localhost:8080/customer") {
contentType(ContentType.Application.Json)
setBody(Customer(3, "Jet", "Brains"))
}ContentNegotiation プラグインは、設定されたシリアライザーを使用してリクエストボディを指定された形式に変換します。
他の登録済み形式でデータを送信するには、ContentType.Application.Xml や ContentType.Application.Cbor などの対応するコンテンツタイプを指定します。
データの受信
サーバーがサポートされているコンテンツタイプを含むレスポンスを返すと、ContentNegotiation プラグインはレスポンスボディを期待される型にデシリアライズできます。
例えば、JSON レスポンスを Customer オブジェクトにデシリアライズするには、body() 関数を呼び出します。
val customer: Customer = client.get("http://localhost:8080/customer/3").body()完全な例については、client-json-kotlinx を参照してください。
