Client Plugin

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

必須の依存関係: io.ktor:ktor-client-content-negotiation

コード例: client-json-kotlinx

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

• クライアントとサーバー間でメディアタイプをネゴシエートすること。これにはAcceptおよびContent-Typeヘッダーを使用します。
• リクエスト送信時およびレスポンス受信時に、コンテンツを特定の形式でシリアライズ/デシリアライズすること。Ktorは、JSON、XML、CBOR、ProtoBufといった形式をすぐに使用できるようにサポートしています。XMLシリアライザーはJVMでのみサポートされていることに注意してください。

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

依存関係の追加

ContentNegotiation

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

Gradle (Kotlin)Gradle (Groovy)Maven

Ktorクライアントに必要なアーティファクトの詳細については、「

クライアント依存関係の追加

既存のプロジェクトにクライアントの依存関係を追加する方法を学びます。

」を参照してください。

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

シリアライズ

kotlinx.serializationコンバーターを使用する前に、セットアップセクションで説明されているように、Kotlin serializationプラグインを追加する必要があります。

JSON

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

kotlinx.serializationGsonJackson

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

Gradle (Kotlin)Gradle (Groovy)Maven

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

Gradle (Kotlin)Gradle (Groovy)Maven

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

Gradle (Kotlin)Gradle (Groovy)Maven

XML

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

Gradle (Kotlin)Gradle (Groovy)Maven

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

CBOR

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

Gradle (Kotlin)Gradle (Groovy)Maven

ProtoBuf

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

Gradle (Kotlin)Gradle (Groovy)Maven

ContentNegotiationのインストール

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

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

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

シリアライザーの設定

JSONシリアライザー

kotlinx.serializationGsonJackson

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

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

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

jsonコンストラクターでは、例えば以下のようにJsonBuilder APIにアクセスできます。

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

完全な例はclient-json-kotlinxにあります。

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

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

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        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によって提供されるシリアライズ設定を調整することもできます。

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メソッドを使用すると、例えば以下のようにCborBuilderによって提供される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
        })
    }
}

ProtoBufシリアライザー

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

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

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

protobufメソッドを使用すると、例えば以下のようにProtoBufBuilderによって提供される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
        })
    }
}

データの送受信

データクラスの作成

データの送受信を行うには、例えば以下のようなデータクラスが必要です。

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

• 組み込みクラス
• シーケンスのデシリアライズ
• フローのシリアライズ

データの送信

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

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）のパラメータとしてデータクラスを指定することでデシリアライズできます。

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

完全な例はclient-json-kotlinxにあります。