Client Plugin

기본 요청

코드 예시: client-default-request

DefaultRequest 플러그인을 사용하면 모든 요청에 대한 기본 파라미터를 구성할 수 있습니다. 예를 들어, 기본 URL 지정, 헤더 추가, 쿼리 파라미터 구성 등을 할 수 있습니다.

의존성 추가

DefaultRequest는 ktor-client-core 아티팩트만 필요하며, 별도의 의존성이 필요하지 않습니다.

DefaultRequest 설치

DefaultRequest를 설치하려면, 클라이언트 구성 블록 내부의 install 함수에 전달하세요:

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.*
//...
val client = HttpClient(CIO) {
    install(DefaultRequest)
}

또는 defaultRequest 함수를 호출하여 필요한 요청 파라미터를 구성할 수 있습니다:

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.*
//...
val client = HttpClient(CIO) {
    defaultRequest {
        // this: DefaultRequestBuilder
    }
}

DefaultRequest 구성

기본 URL

DefaultRequest를 사용하면 요청 URL과 병합될 URL의 기본 부분을 구성할 수 있습니다. 예를 들어, 아래 url 함수는 모든 요청에 대한 기본 URL을 지정합니다:

defaultRequest {
    url("https://ktor.io/docs/")
}

위 구성으로 클라이언트를 사용하여 다음 요청을 수행하면, ...

val response: HttpResponse = client.get("welcome.html")

... 결과 URL은 https://ktor.io/docs/welcome.html이 됩니다. 기본 URL과 요청 URL이 어떻게 병합되는지 알아보려면, DefaultRequest를 참조하세요.

URL 파라미터

url 함수는 또한 URL 구성 요소를 개별적으로 지정할 수 있도록 합니다. 예를 들어:

• HTTP 스킴;
• 호스트 이름;
• 기본 URL 경로;
• 쿼리 파라미터.

url {
    protocol = URLProtocol.HTTPS
    host = "ktor.io"
    path("docs/")
    parameters.append("token", "abc123")
}

헤더

각 요청에 특정 헤더를 추가하려면 header 함수를 사용하세요:

defaultRequest {
    header("X-Custom-Header", "Hello")
}

헤더 중복을 피하려면 appendIfNameAbsent, appendIfNameAndValueAbsent, contains 함수를 사용할 수 있습니다:

defaultRequest {
    headers.appendIfNameAbsent("X-Custom-Header", "Hello")
}

유닉스 도메인 소켓

유닉스 도메인 소켓은 CIO 엔진에서만 지원됩니다.

유닉스 도메인 소켓으로 개별 요청을 빌드할 수 있지만, 소켓 파라미터를 사용하여 기본 요청을 구성할 수도 있습니다.

그렇게 하려면, 소켓 경로와 함께 unixSocket 호출을 defaultRequest 함수에 전달하세요. 예를 들어:

val client = HttpClient(CIO)

// Sending a single request to a Unix domain socket
val response: HttpResponse = client.get("/") {
    unixSocket("/tmp/test-unix-socket-ktor.sock")
}

// Setting up the socket for all requests from that client
val clientDefault = HttpClient(CIO) {
    defaultRequest {
        unixSocket("/tmp/test-unix-socket-ktor.sock")
    }    
}

val response: HttpResponse = clientDefault.get("/")

예시

아래 예시는 다음 DefaultRequest 구성을 사용합니다:

• url 함수는 HTTP 스킴, 호스트, 기본 URL 경로 및 쿼리 파라미터를 정의합니다.
• header 함수는 모든 요청에 사용자 정의 헤더를 추가합니다.

val client = HttpClient(CIO) {
    defaultRequest {
        url {
            protocol = URLProtocol.HTTPS
            host = "ktor.io"
            path("docs/")
            parameters.append("token", "abc123")
        }
        header("X-Custom-Header", "Hello")
    }
}

이 클라이언트로 수행되는 아래 요청은 후반부 경로 세그먼트만 지정하며, DefaultRequest에 구성된 파라미터를 자동으로 적용합니다:

val response: HttpResponse = client.get("welcome.html")
println(response.status)

전체 예시는 여기에서 찾을 수 있습니다: client-default-request.