リクエストの処理
Ktorでは、ルートハンドラーから受信リクエストを処理し、レスポンスを送信できます。
各ルートハンドラーは、callプロパティを通じてApplicationCallを提供します。ApplicationCallは単一のHTTPエクスチェンジを表し、受信リクエストと送信レスポンスの両方へのアクセスを提供します。
ルートハンドラー内では、ApplicationCallを使用して以下を行うことができます。
- ヘッダー、Cookie、接続の詳細などのリクエスト情報にアクセスする。
- パスパラメータを取得する。
- クエリパラメータを取得する。
- データオブジェクト、フォームパラメータ、ファイルなどのリクエストボディの内容を受信する。
一般的なリクエスト情報
call.requestプロパティを使用してリクエストデータにアクセスできます。これはApplicationRequestインスタンスを返し、低レベルのHTTPリクエスト情報へのアクセスを提供します。
たとえば、GETリクエストハンドラー内でcall.request.uriを使用してリクエストURIを取得できます。
routing {
get("/") {
val uri = call.request.uri
call.respondText("Request uri: $uri")
}
}call.respondText()関数は、クライアントにプレーンテキストのレスポンスを返送します。
ヘッダー
すべてのHTTPリクエストヘッダーにアクセスするには、ApplicationRequest.headersプロパティを使用します。
便宜上、Ktorはよく使用されるヘッダーにアクセスするための専用の拡張関数も提供しています。たとえば、.acceptEncoding()、.contentType()、.cacheControl()などがあります。
Cookie
リクエストと一緒に送信されたCookieにアクセスするには、ApplicationRequest.cookiesプロパティを使用します。
Cookieを使用したセッションの処理方法の詳細については、セッションセクションを参照してください。
接続の詳細
ホスト名、ポート、スキームなどの接続の詳細にアクセスするには、ApplicationRequest.localプロパティを使用します。
X-Forwarded- ヘッダー
HTTPプロキシまたはロードバランサーを経由したリクエストに関する情報を収集するには、Forwarded headersプラグインをインストールします。その後、ApplicationRequest.originプロパティを通じてこの情報にアクセスできます。
パスパラメータ
リクエストを処理する際、ApplicationCall.parametersプロパティを使用してパスパラメータの値を取得できます。
たとえば、/user/adminへのリクエストに対して、call.parameters["login"]は"admin"を返します。
get("/user/{login}") {
if (call.parameters["login"] == "admin") {
// ...
}
}クエリパラメータ
URLクエリ文字列のパラメータを取得するには、ApplicationRequest.queryParametersプロパティを使用します。
以下の例では、/products?price=ascへのリクエストからpriceクエリパラメータにアクセスしています。
get("/products") {
if (call.request.queryParameters["price"] == "asc") {
// 低価格から高価格の順に商品を表示する
}
}また、ApplicationRequest.queryString()関数を使用してクエリ文字列全体を取得することもできます。
必須のリクエストパラメータ
リクエストを処理する際、パスパラメータ、クエリパラメータ、ヘッダー、またはCookieから値を取得し、リクエスト処理を続行する前にそれらが存在することを確認するのが一般的です。
すべてのルートハンドラーで欠落している値を手動でチェックする代わりに、Ktorは必須のリクエストデータへのアクセスを簡素化する以下のヘルパー関数を提供しています。
.requireQueryParameter()は、リクエストURLから必須のクエリパラメータを取得します。.requireHeader()は、必須のHTTPヘッダー値を取得します。.requireCookie()は、必須のCookie値を取得し、オプションで指定されたエンコーディングを使用してデコードします。.requirePathParameter()は、ルート定義から必須のパスパラメータを取得します。
各関数は非null値を返すか、要求された値が欠けている場合にMissingRequestParameterExceptionをスローします。
post("/checkout/{cartId}") {
val userId = call.requireCookie("userId")
val cartId = call.requirePathParameter("cartId")
val amount = call.requireQueryParameter("amount").toLong()
// ビジネスロジック
}ボディの内容
リクエストボディにアクセスするには、Ktorのreceive関数を使用します。適切な関数は、生のペイロード、デシリアライズされたオブジェクト、フォームパラメータ、またはマルチパートデータのどれが必要かによって異なります。
生のペイロード
生のボディペイロードにアクセスして手動で解析するには、受信するペイロードの型を受け取るApplicationCall.receive()関数を使用します。
クライアントが次のようなHTTPリクエストを送信したとします。
POST http://localhost:8080/text
Content-Type: text/plain
Hello, world!リクエストボディは、String、ByteArray、またはByteReadChannelとして受信できます。
String
リクエストボディをテキストとして受信するには、.receive<String>()または.receiveText()関数を使用します。
post("/text") {
val text = call.receiveText()
call.respondText(text)
}ByteArray
リクエストのボディをバイト配列として受信するには、.receive<ByteArray>()関数を使用します。
post("/bytes") {
val bytes = call.receive<ByteArray>()
call.respond(String(bytes))
}ByteReadChannel
ボディをByteReadChannelとして非同期に読み取るには、.receive<ByteReadChannel>()または.receiveChannel()関数を使用します。
post("/channel") {
val readChannel = call.receiveChannel()
val text = readChannel.readRemaining().readString()
call.respondText(text)
}また、ByteReadChannelを使用してファイルをアップロードすることもできます。
post("/upload") {
val file = File("uploads/ktor_logo.png")
call.receiveChannel().copyAndClose(file.writeChannel())
call.respondText("A file is uploaded")
}Ktorのチャンネルと、RawSink、RawSource、OutputStreamなどの型との間の変換については、I/O相互運用性を参照してください。
完全な例については、post-raw-dataを参照してください。
オブジェクト
Ktorは、リクエストのメディアタイプをネゴシエートし、コンテンツを必要な型のオブジェクトにデシリアライズするContentNegotiationプラグインを提供しています。
リクエストのコンテンツを受信して変換するには、期待される型を指定してApplicationCall.receive()関数を使用します。
post("/customer") {
val customer = call.receive<Customer>()
customerStorage.add(customer)
call.respondText("Customer stored correctly", status = HttpStatusCode.Created)
}リクエストコンテンツがnullにデシリアライズされる可能性がある場合は、null許容型引数を使用します。
val customer = call.receive<Customer?>()詳細については、Ktor Serverにおけるコンテンツネゴシエーションとシリアライズを参照してください。
フォームパラメータ
.receiveParameters()関数を使用して、x-www-form-urlencodedとmultipart/form-dataの両方の型で送信されたフォームパラメータを受信できます。
たとえば、クライアントが以下のリクエストを送信したとします。
POST http://localhost:8080/signup
Content-Type: application/x-www-form-urlencoded
username=JetBrains&email=example@jetbrains.com&password=foobar&confirmation=foobarコード内でパラメータ値にアクセスするには、次のようにします。
post("/signup") {
val formParameters = call.receiveParameters()
val username = formParameters["username"].toString()
call.respondText("The '$username' account is created")
}完全な例については、post-form-parametersを参照してください。
マルチパートフォームデータ
マルチパートリクエストの一部として送信されたファイルを受信するには、.receiveMultipart()関数を使用します。
マルチパートリクエストデータは順次処理されるため、特定のパートに直接アクセスすることはできません。各パートはフォームフィールド、ファイル、またはその他のバイナリコンテンツを表すことができるため、それぞれの型を個別に処理します。
以下の例では、フォームフィールドとファイルを受信し、ローカルファイルシステムにファイルを保存します。
import io.ktor.server.application.*
import io.ktor.http.content.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.util.cio.*
import io.ktor.utils.io.*
import java.io.File
fun Application.main() {
routing {
post("/upload") {
var fileDescription = ""
var fileName = ""
val multipartData = call.receiveMultipart(formFieldLimit = 1024 * 1024 * 100)
multipartData.forEachPart { part ->
when (part) {
is PartData.FormItem -> {
fileDescription = part.value
}
is PartData.FileItem -> {
fileName = part.originalFileName as String
val file = File("uploads/$fileName")
part.provider().copyAndClose(file.writeChannel())
}
else -> {}
}
part.dispose()
}
call.respondText("$fileDescription is uploaded to 'uploads/$fileName'")
}
}
}デフォルトのファイルサイズ制限
デフォルトでは、バイナリおよびファイルパートは50MiBに制限されています。パートがこの制限を超えると、KtorはIOExceptionをスローします。
呼び出しに対してデフォルトの制限を上書きするには、.receiveMultipart()関数にformFieldLimitパラメータを渡します。
val multipartData = call.receiveMultipart(formFieldLimit = 1024 * 1024 * 100)この例では、制限を100 MiBに設定しています。
フォームフィールド
PartData.FormItemはフォームフィールドを表します。その値にはvalueプロパティを通じてアクセスできます。
when (part) {
is PartData.FormItem -> {
fileDescription = part.value
}
}ファイルアップロード
PartData.FileItemはアップロードされたファイルを表します。ファイルアップロードはバイトストリームとして処理できます。.provider()関数を使用してファイルコンテンツにByteReadChannelとしてアクセスし、宛先へストリーミングします。
when (part) {
is PartData.FileItem -> {
fileName = part.originalFileName as String
val file = File("uploads/$fileName")
part.provider().copyAndClose(file.writeChannel())
}
}.copyAndClose()関数を使用すると、適切なリソースクリーンアップを保証しながら、指定された宛先にファイルコンテンツを書き込みます。
リクエストにContent-Length ヘッダー値が含まれている場合は、それを使用してリクエストボディ全体のサイズを検査できます。
post("/upload") {
val contentLength = call.request.header(HttpHeaders.ContentLength)
// ...
}マルチパートリクエストの場合、Content-Lengthは個別にアップロードされたファイルのサイズではなく、マルチパートボディ全体を表します。
リソースのクリーンアップ
フォームの処理が完了したら、リソースを解放するために.dispose()関数を使用して各マルチパートパートを破棄します。
part.dispose()このサンプルの実行方法については、upload-fileを参照してください。
