[Ktor] 2. Request

Ktor Client 가이드 요약 정리

• Ktor Documents
• 기준 버전: 1.6.2
• 시리즈
  • 1. 클라이언트, Engine
  • 2. Request
  • 3. Response

HttpClient의 request 함수로 HTTP Request를 생성할 수 있다.

• request 함수 시그니처 - 대표적인 예시

inline suspend fun <T> HttpClient.request(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): T

inline suspend fun <T> HttpClient.request(builder: HttpRequestBuilder = HttpRequestBuilder()): T

• 이외 모든 함수 시그니처는 여기에서 확인할 수 있다.

HttpRequestBuilder를 통해 HTTP method, 헤더, 쿠키, 바디 등을 설정할 수 있다.

val response: HttpResponse = client.request("https://ktor.io/") {
    // Configure request parameters exposed by HttpRequestBuilder
}

Request 파라미터

> HTTP method

1. request 함수를 호출할 때 method 프로퍼티를 통해 HTTP method를 지정할 수 있다.
2. val response: HttpResponse = client.request("https://ktor.io/") { method = HttpMethod.Get }
3. request 함수 외에 HttpClient는 각 method 별 기본 함수를 제공한다. - get, post, put 등
4. val response: HttpResponse = client.get("https://ktor.io/")

> 헤더

headers 함수를 이용해 Request에 헤더를 추가할 수 있다.

fun HttpRequestBuilder.headers(block: HeadersBuilder.() -> Unit): HeadersBuilder

val response: HttpResponse = client.get("https://ktor.io/") {
    headers {
        append(HttpHeaders.Accept, "text/html")
        append(HttpHeaders.Authorization, "token")
        append(HttpHeaders.UserAgent, "ktor client")
    }
}

> 쿠키

쿠키 전송은 cookie 함수를 이용한다.

fun HttpRequestBuilder.cookie(
    name: String,
    value: String,
    maxAge: Int = 0,
    expires: GMTDate? = null,
    domain: String? = null,
    path: String? = null,
    secure: Boolean = false,
    httpOnly: Boolean = false,
    extensions: Map<String, String?> = emptyMap()
)

val response: HttpResponse = client.get("https://ktor.io/") {
    cookie(name = "user_name", value = "jetbrains", expires = GMTDate(
        seconds = 0,
        minutes = 0,
        hours = 10,
        dayOfMonth = 1,
        month = Month.APRIL,
        year = 2022
    ))
}

*호출 간 쿠키를 유지해주는 Cookies플러그인도 제공한다.

> Query parameters

parameter 함수를 이용하여 추가한다.

fun HttpRequestBuilder.parameter(key: String, value: Any?)

val response: HttpResponse = client.get("http://localhost:8080/products") {
    parameter("price", "asc")
}

Request body

Request body를 추가하려면 HttpRequestBuilder의
body 프로퍼티를 이용해야 한다. body 프로퍼티는 텍스트 / 클래스 인스턴스 / form data 등 여러 타입을 지원한다. (타입이 Any인 것으로 알 수 있다.)

var body: Any

예시) 텍스트

val response: HttpResponse = client.post("http://localhost:8080/post") {
    body = "Body content"
}

예시) 객체

Json 플러그인을 사용하면 클래스 인스턴스를 Json 형식으로 body에 넣을 수 있다. body 프로퍼티에 클래스 인스턴스를 넣고, content type을 application.json으로 설정하면 된다.

client.post<Unit>("http://localhost:8080/post") {
    contentType(ContentType.Application.Json)
    body = Customer("Jet", "Brains")
}

예시) Form data

submitForm 함수를 이용하여 x-www-form-urlencoded 과 multipart/form-data 타입의 form data 전송이 가능하다.

val response: HttpResponse = client.submitForm(
    url = "http://localhost:8080/get",
    formParameters = Parameters.build {
        append("first_name", "Jet")
        append("last_name", "Brains")
    },
    encodeInQuery = true
)

예시) 파일 업로드

submitFormWithBinaryData 함수를 이용하여 form data에 파일을 포함시킨다. (실행 가능한 코드 예제는 여기에서 확인할 수 있다.)

val response: HttpResponse = client.submitFormWithBinaryData(
    url = "http://localhost:8080/upload",
    formData = formData {
        append("description", "Ktor logo")
        append("image", File("ktor_logo.png").readBytes(), Headers.build {
            append(HttpHeaders.ContentType, "image/png")
            append(HttpHeaders.ContentDisposition, "filename=ktor_logo.png")
        })
    }
) {
      // onUpload 확장함수를 이용하면 업로드 progress 표시도 가능하다.
    onUpload { bytesSentTotal, contentLength ->
        println("Sent $bytesSentTotal bytes from $contentLength")
    }
}

병렬 요청

두 개의 요청을 한 번에 보내는 경우, HttpClient는 첫 번째 요청이 끝날 때까지 두 번째 요청을 대기시킨다. 만약 여러 요청을 한 번에 보내고 싶다면, launch 또는 async 함수를 이용한다.
아래 코드는 두 요청을 비동기적으로 실행한다 (전체 샘플 참고 링크):

val client = HttpClient(CIO)
val firstRequest: Deferred<String> = async { client.get("http://localhost:8080/path1") }
val secondRequest: Deferred<String> = async { client.get("http://localhost:8080/path2") }
val firstRequestContent = firstRequest.await()
val secondRequestContent = secondRequest.await()

요청 취소

launch 함수가 반환한 Job을 이용하여 취소한다.

val client = HttpClient(CIO)
val job = launch {
    val requestContent: String = client.get("http://localhost:8080")
}
job.cancel()