Skip to content
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 を使用するには、ビルドスクリプトに ktor-client-content-negotiation アーティファクトを追加します。

kotlin
implementation(ktorLibs.client.contentNegotiation)
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
groovy
implementation ktorLibs.client.contentNegotiation
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
xml
<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 はデフォルトのシリアライザーを自動的に選択します。必要に応じて、シリアライザーを明示的に指定して設定することもできます。

Ktor クライアントで必要なアーティファクトの詳細については、クライアントの依存関係の追加既存のプロジェクトにクライアントの依存関係を追加する方法を学びます。 を参照してください。

シリアライゼーション ​

kotlinx.serialization コンバーターを使用する前に、セットアップ (Setup) セクションの説明に従って Kotlin serialization プラグインを追加してください。

JSON ​

JSON データのシリアライズとデシリアライズを行うには、プロジェクトにシリアライゼーションライブラリを追加します。Ktor は kotlinx.serialization、Gson、または Jackson をサポートしています。

ビルドスクリプトに ktor-serialization-kotlinx-json アーティファクトを追加します。

kotlin
implementation(ktorLibs.serialization.kotlinx.json)
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
groovy
implementation ktorLibs.serialization.kotlinx.json
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-kotlinx-json-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

ビルドスクリプトに ktor-serialization-gson アーティファクトを追加します。

kotlin
implementation(ktorLibs.serialization.gson)
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
groovy
implementation ktorLibs.serialization.gson
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-gson-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

ビルドスクリプトに ktor-serialization-jackson アーティファクトを追加します。

kotlin
implementation(ktorLibs.serialization.jackson)
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
groovy
implementation ktorLibs.serialization.jackson
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-jackson-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

XML ​

XML のシリアライズとデシリアライズを行うには、ビルドスクリプトに ktor-serialization-kotlinx-xml アーティファクトを追加します。

kotlin
implementation(ktorLibs.serialization.kotlinx.xml)
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
groovy
implementation ktorLibs.serialization.kotlinx.xml
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-kotlinx-xml-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

CBOR ​

CBOR のシリアライズとデシリアライズを行うには、ビルドスクリプトに ktor-serialization-kotlinx-cbor アーティファクトを追加します。

kotlin
implementation(ktorLibs.serialization.kotlinx.cbor)
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
groovy
implementation ktorLibs.serialization.kotlinx.cbor
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-kotlinx-cbor-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

ProtoBuf ​

ProtoBuf のシリアライズとデシリアライズを行うには、ビルドスクリプトに ktor-serialization-kotlinx-protobuf アーティファクトを追加します。

kotlin
implementation(ktorLibs.serialization.kotlinx.protobuf)
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
groovy
implementation ktorLibs.serialization.kotlinx.protobuf
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-kotlinx-protobuf-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

ContentNegotiation のインストール ​

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

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

その後、必要な JSON シリアライザーを設定できます。

シリアライザーの設定 ​

JSON シリアライザー ​

アプリケーションに JSON シリアライザーを登録するには、json() 関数を呼び出します。

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

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

JSON シリアライゼーションをカスタマイズするには、json() コンストラクターに Json 設定を渡します。

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

利用可能な設定オプションについては、JsonBuilder を参照してください。

完全な例については、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 シリアライゼーションをカスタマイズするには、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 シリアライゼーションをカスタマイズするには、cbor() コンストラクターに 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
        })
    }
}

利用可能な設定オプションについては、CborBuilder を参照してください。

ProtoBuf シリアライザー ​

アプリケーションに ProtoBuf シリアライザーを登録するには、protobuf() 関数を呼び出します。

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

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

ProtoBuf シリアライゼーションをカスタマイズするには、protobuf() 関数に 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
        })
    }
}

利用可能なオプションについては、ProtoBufBuilder を参照してください。

Accept ヘッダーの設定 ​

デフォルトでは、ContentNegotiation プラグインは登録されたコンテンツタイプを送信リクエストの Accept ヘッダーに追加します。

Accept ヘッダーを明示的に設定しており、プラグインによって登録済みコンテンツタイプを追加したくない場合は、acceptHeaderMergeStrategy プロパティを ContentTypeMergeStrategy.SkipIfPresent に設定します。

kotlin
val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        register(ContentType.Application.Json, noOpJsonConverter)
        acceptHeaderMergeStrategy = ContentTypeMergeStrategy.SkipIfPresent
    }
}

SkipIfPresent を使用すると、プラグインは既存の Accept ヘッダーを保持します。リクエストに Accept ヘッダーが含まれていない場合、プラグインは通常どおり登録されたコンテンツタイプを追加します。

データの送受信 ​

データクラスの作成 ​

以下の例では、クライアントが送受信するデータを表すために Customer データクラスを使用しています。

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 ライブラリでは、以下の型のシリアライズ/デシリアライズがサポートされています。

データの送信 ​

リクエストボディでクラスのインスタンスを送信するには、setBody() 関数を使用してこのインスタンスを割り当て、contentType() 関数を使用してコンテンツタイプを設定します。

以下の例は、Customer オブジェクトを JSON として送信します。

kotlin
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() 関数を呼び出します。

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

完全な例については、client-json-kotlinx を参照してください。