Client Plugin

콘텐츠 인코딩(Content encoding

[//]: # (title: 콘텐츠 인코딩(Content encoding))

필수 의존성: io.ktor:ktor-client-encoding

코드 예제: client-content-encoding

Ktor 클라이언트는 특정 압축 알고리즘(예: gzip, deflate)을 활성화하고 설정을 구성할 수 있는 ContentEncoding 플러그인을 제공합니다.

이 플러그인은 다음과 같은 기능을 제공합니다:

• 지정된 품질 값(quality value)으로 Accept-Encoding 헤더를 설정합니다.
• 선택적으로 요청 본문(request body)을 인코딩합니다.
• 서버로부터 수신된 콘텐츠를 디코딩하여 원본 페이로드를 얻습니다.

의존성 추가

ContentEncoding을 사용하려면 빌드 스크립트에 ktor-client-encoding 아티팩트를 추가하세요:

Gradle (Kotlin)Gradle (Groovy)Maven

TIP

Ktor 클라이언트에 필요한 아티팩트에 대한 자세한 내용은

클라이언트 의존성 추가

Learn how to add client dependencies to an existing project.

에서 확인할 수 있습니다.

ContentEncoding 설치

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

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

ContentEncoding 구성

인코더 활성화

어떤 인코더를 지원할지 구성하고 (Accept-Encoding 헤더에 사용되는) 품질 값을 지정할 수 있습니다.

아래 예제는 사용자 정의 품질 값으로 deflate 및 gzip 인코더를 활성화하는 방법을 보여줍니다:

val client = HttpClient(CIO) {
    install(ContentEncoding) {
        deflate(1.0F)
        gzip(0.9F)
    }
}

필요한 경우, ContentEncoder 인터페이스를 구현하여 사용자 정의 인코더를 만들고 customEncoder() 함수를 사용하여 등록할 수 있습니다.

mode 속성 설정

기본적으로 ContentEncoding은 응답 압축 해제(decompression)만 처리합니다. mode 속성을 사용하여 플러그인이 작동하는 방식을 정의할 수 있습니다.

사용 가능한 값은 다음과 같습니다:

ContentEncodingConfig.Mode.DecompressResponse

응답만 압축 해제합니다. 이것이 기본 모드입니다.

ContentEncodingConfig.Mode.CompressRequest

요청 본문 압축만 활성화합니다.

ContentEncodingConfig.Mode.All

응답 압축 해제와 요청 압축을 모두 활성화합니다.

요청 본문 인코딩

요청 압축을 활성화하려면 mode 속성을 설정하고 HttpRequestBuilder 블록 내부에서 compress() 함수를 사용하세요:

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.compression.*
//...
val client = HttpClient(CIO) {
    install(ContentEncoding) {
        mode = ContentEncodingConfig.Mode.CompressRequest
        gzip()
    }
}
client.post("/upload") {
    compress("gzip")
    setBody(someLongBody)
}

이 예제에서:

• mode = ContentEncodingConfig.Mode.CompressRequest는 요청 압축을 활성화합니다.
• gzip()은 gzip 인코더를 등록합니다.
• compress("gzip")은 이 특정 요청에 gzip 압축을 적용합니다.
• Content-Encoding 헤더가 자동으로 추가됩니다.

응답 처리에 대한 자세한 내용은 응답 수신을 참조하세요.