HTTP 컴포넌트

원문 보기 위키 갱신 2026.10.11

HTTP 컴포넌트는 외부 HTTP 자원을 호출하기 위한 HTTP 기반 엔드포인트를 제공해요. HTTP를 이용해 외부 서버를 호출하는 클라이언트 역할을 하는 거죠. 이 컴포넌트는 Camel 2.3부터 제공됐고 producer만 지원합니다.

출처: 문서

본문

Camel 2.3부터 지원

producer만 지원해요

HTTP 컴포넌트는 외부 HTTP 자원을 호출하기 위한 HTTP 기반 엔드포인트를 제공해요. HTTP를 이용해 외부 서버를 호출하는 클라이언트 역할을 하는 거죠.

Maven 사용자는 이 컴포넌트를 위해 pom.xml에 다음 의존성을 추가해야 해요.

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-http</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>

URI 형식 (URI Format)

http:hostname[:port][/resourceUri][?options]

기본값으로 HTTP는 80, HTTPS는 443 포트를 사용해요.

옵션 설정 방법 (Configuring Options)

Camel 컴포넌트는 두 단계로 나눠 설정합니다:

component level
endpoint level

컴포넌트 옵션 설정 (Configuring Component Options)

컴포넌트 레벨에서는 엔드포인트들이 이어서 물려받는 일반적이고 공유되는 설정을 해요. 가장 상위의 설정 레벨이죠.

예를 들어 컴포넌트에는 보안 설정, 인증용 자격 증명, 네트워크 연결 URL 같은 것들이 있을 수 있어요.

컴포넌트에 따라 옵션이 몇 개뿐인 것도 있고 아주 많은 것도 있어요. 컴포넌트는 보통 널리 쓰이는 기본값이 미리 설정되어 있어서, 몇 가지 옵션만 설정하거나 아예 하나도 건드리지 않아도 되는 경우가 많아요.

컴포넌트는 다음 방법으로 설정할 수 있어요:

the Component DSL.
in a configuration file (application.properties, *.yaml files, etc).
directly in the Java code.

엔드포인트 옵션 설정 (Configuring Endpoint Options)

엔드포인트는 옵션이 많아서 설정에 시간을 더 쓰게 될 거예요. 이 옵션들이 엔드포인트가 원하는 일을 하도록 커스터마이즈해 줘요. 옵션은 엔드포인트가 consumer(from)로 쓰이는지, producer(to)로 쓰이는지, 둘 다인지에 따라 분류되기도 해요.

엔드포인트 설정은 대부분 엔드포인트 URI에 _path_와 query 파라미터로 바로 하는 경우가 많아요. Java에서 엔드포인트와 데이터 포맷을 _타입 세이프_하게 설정하려면 Endpoint DSL과 DataFormat DSL을 쓸 수도 있어요.

옵션을 설정할 때 좋은 습관은 Property Placeholders를 사용하는 거예요.

프로퍼티 플레이스홀더는 이런 장점이 있어요:

They help prevent using hardcoded urls, port numbers, sensitive information, and other settings.
They allow externalizing the configuration from the code.
They help the code to become more flexible and reusable.

다음 두 섹션에서 모든 옵션을 나열해요. 먼저 컴포넌트 옵션, 그다음 엔드포인트 옵션 순서예요.

컴포넌트 옵션 (Component Options)

HTTP 컴포넌트가 지원하는 옵션은 아래와 같아요.

Name	Description	Default	Type
lazyStartProducer (producer)	producer를 lazy(첫 메시지 시점)로 시작할지 여부예요. lazy 시작을 쓰면 producer가 시작 중 실패해서 라우트 시작이 실패하는 상황에서도 CamelContext와 라우트를 시작할 수 있고, 시작 실패 처리를 Camel의 라우팅 에러 핸들러로 넘길 수 있어요. 다만 첫 메시지를 처리하는 시점에 producer를 만들고 시작하는 데 시간이 조금 걸려서 전체 처리 시간이 길어질 수 있다는 점은 유의하세요.	false	boolean
logHttpActivity (producer)	HTTP 요청과 응답 로깅을 활성화해요. 로깅 옵션을 제어하려면 LoggingHttpActivityListener를 httpActivityListener로 직접 지정할 수 있어요.	false	boolean
skipControlHeaders (producer)	Camel 컨트롤 헤더(CamelHttp… 헤더)를 이 엔드포인트에 영향을 주지 않도록 건너뛸지 여부예요. 앞선 HTTP 컴포넌트가 심은 컨트롤 헤더는 CamelHttpPath, CamelHttpQuery처럼 이 Camel 컴포넌트의 동작 방식에 영향을 줄 수 있어요.	false	boolean
skipRequestHeaders (producer)	Camel 헤더를 전부 HTTP 요청 헤더로 매핑하지 않을지 여부예요. HTTP 서비스를 호출할 때 커스텀 헤더가 전혀 필요 없다는 걸 알고 있다면 유용해요.	false	boolean
skipResponseHeaders (producer)	HTTP 응답 헤더를 전부 Camel 헤더로 매핑하지 않을지 여부예요.	false	boolean
contentTypeCharsetEnabled (producer (advanced))	Content-Type 헤더가 문자열 기반 콘텐츠에 charset을 자동으로 붙일지 여부예요.	true	boolean
cookieStore (producer (advanced))	커스텀 org.apache.hc.client5.http.cookie.CookieStore를 사용해요. 기본값은 메모리에만 쿠키를 보관하는 org.apache.hc.client5.http.cookie.BasicCookieStore예요. bridgeEndpoint=true이면 그냥 브리지(프록시 역할)하는 상황이라 쿠키를 저장하면 안 되기 때문에 쿠키 스토어가 noop 쿠키 스토어로 강제된다는 점에 주의하세요.		CookieStore
copyHeaders (producer (advanced))	이 옵션이 true면 IN exchange 헤더를 copy 전략에 따라 OUT exchange 헤더로 복사해요. false로 두면 HTTP 응답에서 온 헤더만 담게 되죠(IN 헤더를 전파하지 않아요).	true	boolean
followRedirects (producer (advanced))	HTTP 요청이 리다이렉트를 따라갈지 여부예요. 기본값으로 HTTP 요청은 리다이렉트를 따라가지 않아요.	false	boolean
httpActivityListener (producer (advanced))	Autowired 커스텀 activity listener를 사용해요.		HttpActivityListener
responsePayloadStreamingThreshold (producer (advanced))	이 임계값(바이트)은 응답 페이로드를 바이트 배열로 메모리에 담을지, 스트리밍 방식으로 다룰지 결정해요. -1로 설정하면 항상 스트리밍 모드를 사용합니다.	8192	int
userAgent (producer (advanced))	커스텀 HTTP User-Agent 요청 헤더를 설정해요.		String
allowJavaSerializedObject (advanced)	요청이 context-type=application/x-java-serialized-object를 쓸 때 java 직렬화를 허용할지 여부예요. 기본값은 꺼져 있어요. 켜면 요청에서 들어온 데이터를 Java로 역직렬화하는데, 이는 잠재적인 보안 위험이 될 수 있다는 점을 유의하세요.	false	boolean
authCachingDisabled (advanced)	인증 스킴 캐싱을 비활성화해요.	false	boolean
automaticRetriesDisabled (advanced)	자동 요청 복구와 재실행을 비활성화해요. 서버가 HTTP 429 (Too Many Requests)로 응답하면서 긴 Retry-After 헤더를 담아 보낼 때 유용해요. 이 헤더가 있으면 클라이언트가 재시도 전에 그 시간만큼 기다리게 되거든요(멈춘 것처럼 보이죠).	false	boolean
autowiredEnabled (advanced)	autowiring을 활성화할지 여부예요. 레지스트리에서 일치하는 타입의 인스턴스가 하나뿐인지 찾아 자동으로 autowiring 옵션(해당 옵션은 autowired로 표시돼 있어야 함)을 설정하는 데 쓰여요. JDBC 데이터 소스, JMS 커넥션 팩토리, AWS 클라이언트 같은 걸 자동 설정할 수 있죠.	true	boolean
clientConnectionManager (advanced)	커넥션 관리용으로 커스텀하고 공유되는 HttpClientConnectionManager를 사용해요. 이걸 설정하면 이 컴포넌트가 만드는 모든 엔드포인트에 항상 이것이 사용돼요.		HttpClientConnectionManager
connectionsPerRoute (advanced)	라우트당 최대 커넥션 수예요.	20	int
connectionStateDisabled (advanced)	커넥션 상태 추적을 비활성화해요.	false	boolean
connectionTimeToLive (advanced)	커넥션이 살아 있는 시간이에요. 시간 단위는 밀리초이고, 기본값은 항상 keepAlive예요.		long
contentCompressionDisabled (advanced)	자동 콘텐츠 압축 해제를 비활성화해요.	false	boolean
cookieManagementDisabled (advanced)	상태(쿠키) 관리를 비활성화해요.	false	boolean
defaultUserAgentDisabled (advanced)	사용자가 아무것도 지정하지 않았을 때 이 빌더가 설정하는 기본 user agent를 비활성화해요.	false	boolean
httpBinding (advanced)	Camel 메시지와 HttpClient 사이의 매핑을 제어하려고 커스텀 HttpBinding을 사용해요.		HttpBinding
httpClientConfigurer (advanced)	사용될 HttpClient를 설정하려고 커스텀 HttpClientConfigurer를 사용해요.		HttpClientConfigurer
httpConfiguration (advanced)	공유 HttpConfiguration을 기본 설정으로 사용해요.		HttpConfiguration
httpContext (advanced)	요청을 실행할 때 커스텀 org.apache.hc.core5.http.protocol.HttpContext를 사용해요.		HttpContext
maxTotalConnections (advanced)	최대 커넥션 수예요.	200	int
redirectHandlingDisabled (advanced)	자동 리다이렉트 처리를 비활성화해요.	false	boolean
useSystemProperties (advanced)	HTTP Client를 설정할 때 System Properties를 설정 폴백으로 사용해요.	false	boolean
headerFilterStrategy (filter)	Camel 메시지와 주고받는 헤더를 걸러 내려고 커스텀 org.apache.camel.spi.HeaderFilterStrategy를 사용해요.		HeaderFilterStrategy
nonProxyHosts (proxy)	프록시를 우회해야 하는 호스트의 쉼표 구분 목록이에요. 와일드카드(예: localhost,.example.com,192.168..)를 지원합니다.		String
proxyAuthDomain (proxy)	NTLM에 사용할 프록시 인증 도메인이에요.		String
proxyAuthHost (proxy)	폐기 예정 프록시 서버 호스트예요.		String
proxyAuthMethod (proxy)
사용할 프록시 인증 방식이에요 (NTLM은 폐기 예정).

Enum values:

Basic
Digest
NTLM

프록시 서버 접속 프로토콜 스킴이에요. 목표 엔드포인트의 스킴과 무관하게 기본값은 http예요. 대부분의 회사 HTTP 프록시는 리스너 포트에서 일반 HTTP 커넥션을 기대하기 때문이죠.

Enum values:

http
https

TLS 핸드셰이크 중 호스트 이름 검증을 어떻게 수행할지 제어해요. CLIENT(기본값)는 설정된 x509HostnameVerifier에 완전히 맡기고 httpclient 5.5 이전의 동작을 유지하며, NoopHostnameVerifier이면 검증이 꺼져요. BUILTIN은 설정된 검증기를 무시하고 JDK SSLParameters의 호스트 이름 검사만 써요. BOTH는 JDK 내장 검사를 먼저 돌리고 그다음 설정된 검증기를 실행하죠. BUILTIN 또는 BOTH에서는 NoopHostnameVerifier로도 내장 검사를 우회할 수 없어요. 커스텀 검증기 시맨틱이 필요 없다면 더 강한 기본 보안을 위해 BOTH를 권해요.

Enum values:

CLIENT
BUILTIN
BOTH

엔드포인트 옵션 (Endpoint Options)

HTTP 엔드포인트는 URI 문법으로 설정해요:

http://httpUri

다음 _path_와 query 파라미터를 사용해요:

Path 파라미터 (Path Parameters)

Name	Description	Default	Type
httpUri (common)	필수 호출할 HTTP 엔드포인트의 URL이에요.		URI

Query 파라미터 (Query Parameters)

Name	Description	Default	Type
disableStreamCache (common)	원시 입력 스트림을 캐시할지 여부를 정해요. Camel consumer(camel-servlet, camel-jetty 등)는 기본적으로 입력 스트림을 캐시해서 여러 번 읽을 수 있게 하고, Camel이 스트림에서 모든 데이터를 가져올 수 있도록 보장해요. 다만 원시 스트림에 직접 접근해야 할 때, 예를 들어 파일이나 다른 영구 저장소로 바로 스트리밍할 때는 이 옵션을 true로 설정할 수 있어요. 이 옵션이 false면 DefaultHttpBinding이 요청 입력 스트림을 스트림 캐시에 복사해서 메시지 본문에 넣어 여러 번 읽을 수 있게 해요. Servlet으로 엔드포인트를 브리지/프록시한다면 메시지 페이로드를 여러 번 읽을 필요가 없는 경우 이 옵션을 켜서 성능을 개선하는 걸 고려해 보세요. producer(camel-http)는 기본적으로 응답 본문 스트림을 캐시해요. 이 옵션을 true로 설정하면 producer는 응답 본문 스트림을 캐시하지 않고 응답 스트림을 있는 그대로 씁니다(스트림은 한 번만 읽을 수 있어요).	false	boolean
headerFilterStrategy (common (advanced))	Camel 메시지와 주고받는 헤더를 걸러 내려고 커스텀 HeaderFilterStrategy를 사용해요.		HeaderFilterStrategy
bridgeEndpoint (producer)	이 옵션이 true면 HttpProducer가 Exchange.HTTP_URI 헤더를 무시하고 요청에 엔드포인트의 URI를 사용해요. throwExceptionOnFailure 옵션을 false로 두면 HttpProducer가 모든 fault 응답을 그대로 돌려보낼 수 있어요.	false	boolean
connectionClose (producer)	HTTP 요청에 Connection Close 헤더를 반드시 추가할지 여부를 지정해요. 기본값으로 connectionClose는 false예요.	false	boolean
httpMethod (producer)
사용할 HTTP 메서드를 설정해요. 이 옵션이 설정되어 있으면 HttpMethod 헤더가 이 옵션을 덮어쓰지 못해요.

Enum values:

GET
POST
PUT
DELETE
HEAD
OPTIONS
TRACE
PATCH

사용할 프록시 인증 방식이에요 (NTLM은 폐기 예정).

Enum values:

Basic
Bearer
NTLM

Enum values:

http
https

허용할 인증 방식이에요. Basic, Bearer, NTLM을 쉼표로 구분한 목록으로 지정합니다 (NTLM은 폐기 예정).

Enum values:

Basic
Bearer
NTLM

Enum values:

CLIENT
BUILTIN
BOTH

oauth2CacheTokens가 켜져 있을 때 캐시된 OAuth2 토큰을 요청들 사이에서 어떻게 공유할지 정해요. FULL_URI는 쿼리를 포함한 요청 URI별로 토큰 하나를 쓰고, HOST_AND_PATH는 경로별로, HOST_ONLY는 스킴·호스트·포트별로 하나씩 써요. 토큰 요청 자체는 요청 URI에 의존하지 않기 때문에 HOST_AND_PATH와 HOST_ONLY가 더 적은 토큰을 요청해요.

Enum values:

HOST_ONLY
HOST_AND_PATH
FULL_URI

메시지 헤더 (Message Headers)

HTTP 컴포넌트가 지원하는 메시지 헤더는 아래와 같아요:

Name	Description	Type
Content-Encoding (producer) Constant: `CONTENT_ENCODING`	HTTP content encoding이에요. gzip 같은 content encoding을 제공하려고 IN과 OUT 메시지 양쪽에 설정돼요.	String
CamelHttpResponseCode (producer) Constant: `HTTP_RESPONSE_CODE`	외부 서버의 HTTP 응답 코드예요. 정상이면 200이에요.	int
CamelHttpResponseText (producer) Constant: `HTTP_RESPONSE_TEXT`	외부 서버의 HTTP 응답 텍스트예요.	String
CamelHttpQuery (producer) Constant: `HTTP_QUERY`	URI 파라미터예요. 엔드포인트에 직접 설정한 기존 URI 파라미터를 덮어써요.	String
CamelHttpProtocolVersion (producer) Constant: `HTTP_PROTOCOL_VERSION`	사용된 http 프로토콜의 버전이에요.	String
Host (producer) Constant: `HTTP_HEADER_HOST`	대상 호스트예요.	String
CamelRestHttpUri (producer) Constant: `REST_HTTP_URI`	rest http URI예요.	String
CamelHttpUri (producer) Constant: `HTTP_URI`	호출할 URI예요. 엔드포인트에 직접 설정한 기존 URI를 덮어써요. 이 URI는 호출할 http 서버의 URI예요. 보안 같은 엔드포인트 옵션을 설정할 수 있는 Camel 엔드포인트 URI와는 달라요. 이 헤더는 그런 기능을 지원하지 않고, 오직 http 서버의 URI만 다뤄요.	String
CamelHttpPath (producer) Constant: `HTTP_PATH`	요청 URI의 경로예요. 이 헤더는 HTTP_URI와 함께 요청 URI를 만드는 데 사용돼요.	String
CamelRestHttpQuery (producer) Constant: `REST_HTTP_QUERY`	rest http query예요.	String
CamelHttpRawQuery (producer) Constant: `HTTP_RAW_QUERY`	http raw query예요.	String
CamelHttpMethod (producer) Constant: `HTTP_METHOD`
사용할 http 메서드예요.

Enum values:

GET
PATCH
POST
PUT
DELETE
HEAD
OPTIONS
TRACE

사용법 (Usage)

메시지 본문 (Message Body)

Camel은 외부 서버에서 받은 HTTP 응답을 OUT 본문에 저장해요. IN 메시지의 모든 헤더는 OUT 메시지로 복사되기 때문에 라우팅 중에도 헤더가 유지돼요. 게다가 HTTP 응답 헤더도 OUT 메시지 헤더에 추가해요.

시스템 프로퍼티 사용 (Using System Properties)

useSystemProperties를 true로 설정하면 HTTP Client가 다음 System Properties를 찾아서 사용해요:

ssl.TrustManagerFactory.algorithm
javax.net.ssl.trustStoreType
javax.net.ssl.trustStore
javax.net.ssl.trustStoreProvider
javax.net.ssl.trustStorePassword
java.home
ssl.KeyManagerFactory.algorithm
javax.net.ssl.keyStoreType
javax.net.ssl.keyStore
javax.net.ssl.keyStoreProvider
javax.net.ssl.keyStorePassword
http.proxyHost
http.proxyPort
http.nonProxyHosts
http.keepAlive
http.maxConnections

응답 코드 (Response code)

Camel은 HTTP 응답 코드에 따라 이렇게 처리해요:

Response code is in the range 100..299, Camel regards it as a success response.
Response code is in the range 300..399, Camel regards it as a redirection response and will throw a HttpOperationFailedException with the information.
Response code is 400+, Camel regards it as an external server failure and will throw a HttpOperationFailedException with the information.

throwExceptionOnFailure

throwExceptionOnFailure 옵션을 false로 설정하면 실패 응답 코드에 대해 HttpOperationFailedException이 던져지지 않아요. 이렇게 하면 원격 서버의 어떤 응답이든 받을 수 있죠.

HTTP 429 Too Many Requests 처리 (Handling HTTP 429 Too Many Requests)

서버가 HTTP 429 (Too Many Requests)로 응답하고 Retry-After 헤더를 담아 보내면, 하위의 Apache HttpClient 5가 지정된 시간만큼 기다렸다가 요청을 재시도해요. 서버가 긴 재시도 지연을 돌려주면(예: 한 시간을 뜻하는 Retry-After: 3600) HTTP 컴포넌트는 그 시간 동안 멈춘 것처럼 보여요.

이를 피하려면 컴포넌트에서 자동 재시도를 비활성화하면 돼요:

Java 전용: 프로그래밍 방식의 HttpComponent 설정

HttpComponent httpComponent = context.getComponent("https", HttpComponent.class);
httpComponent.setAutomaticRetriesDisabled(true);

엔드포인트의 URI 옵션으로도 할 수 있어요:

https://myhost/mypath?automaticRetriesDisabled=true

자동 재시도를 끄면 429 응답이 에러로 처리되고 HttpOperationFailedException이 곧바로 던져져요 (throwExceptionOnFailure=false인 경우는 제외).

예외 (Exceptions)

HttpOperationFailedException 예외에는 다음 정보가 담겨 있어요:

The HTTP status code
The HTTP status line (text of the status code)
Redirect location if server returned a redirect
Response body as a java.lang.String, if server provided a body as response

어떤 HTTP 메서드가 사용될까 (Which HTTP method will be used)

어떤 HTTP 메서드를 쓸지 판단할 때는 다음 알고리즘을 사용해요: 1. 엔드포인트 설정(httpMethod)으로 지정한 메서드를 사용해요. 2. 헤더(Exchange.HTTP_METHOD)로 지정한 메서드를 사용해요. 3. 헤더에 query string이 있으면 GET이에요. 4. 엔드포인트에 query string이 설정돼 있으면 GET이에요. 5. 보낼 데이터가 있으면(본문이 null이 아니면) POST예요. 6. 그 외에는 GET이에요.

호출할 URI 설정 (Configuring URI to call)

HTTP producer의 URI는 엔드포인트 URI에서 바로 설정할 수 있어요. 아래 라우트에서 Camel은 HTTP로 외부 서버 oldhost를 호출해요.

from("direct:start")
    .to("http://oldhost");

<route>
  <from uri="direct:start"/>
  <to uri="http://oldhost"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - to:
            uri: http://oldhost

메시지에 Exchange.HTTP_URI 키를 가진 헤더를 추가하면 HTTP 엔드포인트 URI를 덮어쓸 수 있어요.

from("direct:start")
  .setHeader("CamelHttpUri", constant("http://newhost"))
  .to("http://oldhost");

<route>
  <from uri="direct:start"/>
  <setHeader name="CamelHttpUri">
    <constant>http://newhost</constant>
  </setHeader>
  <to uri="http://oldhost"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - setHeader:
            name: CamelHttpUri
            constant: "http://newhost"
        - to:
            uri: http://oldhost

위 예제에서 엔드포인트는 http://oldhost로 설정돼 있지만, Camel은 http://newhost를 호출해요. http 엔드포인트가 bridge 모드로 동작 중이면 Exchange.HTTP_URI 메시지 헤더를 무시해요.

URI 파라미터 설정 (Configuring URI Parameters)

http producer는 HTTP 서버로 보낼 URI 파라미터를 지원해요. URI 파라미터는 엔드포인트 URI에 바로 넣거나, 메시지에 Exchange.HTTP_QUERY 키를 가진 헤더로 넘길 수 있어요.

from("direct:start")
  .to("http://oldhost?order=123&detail=short");

<route>
  <from uri="direct:start"/>
  <to uri="http://oldhost?order=123&amp;detail=short"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - to:
            uri: http://oldhost
            parameters:
              order: 123
              detail: short

헤더로 옵션을 제공할 수도 있어요:

from("direct:start")
  .setHeader("CamelHttpQuery", constant("order=123&detail=short"))
  .to("http://oldhost");

<route>
  <from uri="direct:start"/>
  <setHeader name="CamelHttpQuery">
    <constant>order=123&amp;detail=short</constant>
  </setHeader>
  <to uri="http://oldhost"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - setHeader:
            name: CamelHttpQuery
            constant: "order=123&detail=short"
        - to:
            uri: http://oldhost

HTTP producer에 http 메서드(GET/PATCH/POST/PUT/DELETE/HEAD/OPTIONS/TRACE) 지정하기 (How to set the http method (GET/PATCH/POST/PUT/DELETE/HEAD/OPTIONS/TRACE) to the HTTP producer)

HTTP 컴포넌트는 메시지 헤더를 설정하는 방식으로 HTTP 요청 메서드를 지정할 수 있게 해 줘요. 예제를 볼까요:

from("direct:start")
  .setHeader("CamelHttpMethod", constant("POST"))
  .to("http://www.google.com")
  .to("mock:results");

<route>
  <from uri="direct:start"/>
  <setHeader name="CamelHttpMethod">
      <constant>POST</constant>
  </setHeader>
  <to uri="http://www.google.com"/>
  <to uri="mock:results"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - setHeader:
            name: CamelHttpMethod
            constant: POST
        - to:
            uri: http://www.google.com
        - to:
            uri: mock:results

클라이언트 타임아웃 사용 - SO_TIMEOUT (Using client timeout - SO_TIMEOUT)

HttpSOTimeoutTest 단위 테스트를 보세요.

프록시 설정 (Configuring a Proxy)

HTTP 컴포넌트는 프록시를 설정하는 방법을 제공해요.

from("direct:start")
  .to("http://oldhost?proxyAuthHost=www.myproxy.com&proxyAuthPort=80");

<route>
  <from uri="direct:start"/>
  <to uri="http://oldhost?proxyAuthHost=www.myproxy.com&amp;proxyAuthPort=80"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - to:
            uri: http://oldhost
            parameters:
              proxyAuthHost: www.myproxy.com
              proxyAuthPort: 80

proxyAuthUsername과 proxyAuthPassword 옵션으로 프록시 인증하는 방법도 지원해요.

URI 밖에서 프록시 설정 (Using proxy settings outside of URI)

폐기 예정

System 프로퍼티 충돌을 피하려면 프록시 설정을 CamelContext나 URI에서만 하세요. Java DSL :

Java 전용: 프로그래밍 방식의 CamelContext 글로벌 옵션 설정 (폐기 예정)

context.getGlobalOptions().put("http.proxyHost", "172.168.18.9");
context.getGlobalOptions().put("http.proxyPort", "8080");

Spring XML

XML 전용: Spring XML 글로벌 옵션 설정 (폐기 예정)

<camelContext>
    <globalOptions>
        <globalOption key="http.proxyHost" value="172.168.18.9"/>
        <globalOption key="http.proxyPort" value="8080"/>
    </globalOptions>
</camelContext>

Camel은 먼저 Java System이나 CamelContext 프로퍼티에서 설정을 적용하고, 그다음 엔드포인트 프록시 옵션이 있으면 적용해요. 그래서 시스템 프로퍼티를 엔드포인트 옵션으로 덮어쓸 수 있죠.

사용할 스킴을 명시적으로 설정하는 http.proxyScheme 프로퍼티도 있어요.

중요 위에서 본 것 같은 GlobalOptions 사용은 폐기 예정이에요. 대신 HTTP 컴포넌트 레벨에서 프록시를 설정하세요.

charset 설정 (Configuring charset)

POST로 데이터를 보낼 때는 Exchange 프로퍼티로 charset을 설정할 수 있어요:

Java 전용: 프로그래밍 방식의 exchange 프로퍼티 설정

exchange.setProperty(Exchange.CHARSET_NAME, "ISO-8859-1");

scheduled poll 예제 (Example with scheduled poll)

이 예제는 10초마다 Google 홈페이지를 폴링해서 페이지를 message.html 파일에 기록해요:

from("timer://foo?fixedRate=true&delay=0&period=10000")
  .to("http://www.google.com")
  .setHeader("CamelFileName", constant("message.html"))
  .to("file:target/google");

<route>
  <from uri="timer://foo?fixedRate=true&amp;delay=0&amp;period=10000"/>
  <to uri="http://www.google.com"/>
  <setHeader name="CamelFileName">
    <constant>message.html</constant>
  </setHeader>
  <to uri="file:target/google"/>
</route>

- route:
    from:
      uri: timer://foo
      parameters:
        fixedRate: true
        delay: 0
        period: 10000
      steps:
        - to:
            uri: http://www.google.com
        - setHeader:
            name: CamelFileName
            constant: message.html
        - to:
            uri: file:target/google

엔드포인트 URI에서 온 URI 파라미터 (URI Parameters from the endpoint URI)

이 예제의 엔드포인트 URI는 웹 브라우저에 입력하는 것과 똑같은 완전한 URI예요. 여러 URI 파라미터는 웹 브라우저에서처럼 & 문자로 구분해서 설정하면 돼요. Camel은 여기서 아무 트릭도 쓰지 않아요.

Java 전용: ProducerTemplate 테스트 API 사용

// we query for Camel at the Google page
template.sendBody("http://www.google.com/search?q=Camel", null);

메시지에서 온 URI 파라미터 (URI Parameters from the Message)

Java 전용: 헤더를 쓰는 ProducerTemplate 테스트 API 사용

Map headers = new HashMap();
headers.put(Exchange.HTTP_QUERY, "q=Camel&lr=lang_en");
// we query for Camel and English language at Google
template.sendBody("http://www.google.com/search", null, headers);

위 헤더 값은 ?로 시작하면 안 된다는 점에 유의하세요. 파라미터 구분은 평소처럼 & 문자로 하면 돼요.

응답 코드 가져오기 (Getting the Response Code)

HTTP 응답 코드는 Exchange.HTTP_RESPONSE_CODE로 Out 메시지 헤더에서 값을 가져오면 돼요.

Java 전용: 응답 코드 확인용 ProducerTemplate과 Processor 사용

Exchange exchange = template.send("http://www.google.com/search", e -> {
    e.getIn().setHeader("CamelHttpQuery", "hl=en&q=activemq");
});
Message out = exchange.getMessage();
int responseCode = out.getHeader("CamelHttpResponseCode", Integer.class);

Camel 파라미터로 Apache HTTP client의 특정 프로퍼티 정의 (Defining specific properties of Apache HTTP client via Camel parameters)

라우트에 설정할 수 있는 여러 파라미터가 Apache HTTP Client의 동작에 영향을 줘요.

대부분의 옵션은 여기에 있어요: Apache HttpClient Request Config Builder.

httpClient.authenticationEnabled - Determines whether authentication should be handled automatically.
httpClient.circularRedirectsAllowed - Determines whether circular redirects (redirects to the same location) should be allowed.
httpClient.connectionKeepAlive - Determines the default of value of connection keep-alive time period when not explicitly communicated by the origin server with a Keep-Alive response header.
httpClient.connectionRequestTimeout - Determines the connection lease request timeout used when requesting a connection from the connection manager.
httpClient.contentCompressionEnabled - Determines whether the target server is requested to compress content.
httpClient.cookieSpec - Determines the name of the cookie specification to be used for HTTP state management.
httpClient.defaultKeepAlive - Determines the default keep-alive
httpClient.expectContinueEnabled - Determines whether the 'Expect: 100-Continue' handshake is enabled for entity enclosing methods.
httpClient.hardCancellationEnabled - Determines whether request cancellation should kill the underlying connection.
httpClient.maxRedirects - Determines the maximum number of redirects to be followed.
httpClient.protocolUpgradeEnabled - Determines whether the client server should automatically attempt to upgrade to a safer or a newer version of the protocol, whenever possible.
httpClient.redirectsEnabled - Determines whether redirects should be handled automatically.
httpClient.responseTimeout - Determines the timeout until arrival of a response from the opposite endpoint.

쿠키 끄기 (Disabling Cookies)

CookieStore에서 쿠키를 끄려면 URI 옵션 httpClient.cookieSpec=ignore를 추가해서 HTTP Client가 쿠키를 무시하게 하면 돼요. 이 설정은 Cookie 헤더에 수동으로 넣은 쿠키에는 영향을 주지 않아요.

스트리밍 메시지 본문과 basic auth (Basic auth with the streaming message body)

NonRepeatableRequestException을 피하려면 authenticationPreemptive=true 옵션을 추가해 preemptive basic 인증을 하면 돼요.

OAuth2 지원 (OAuth2 Support)

Authorization Server에서 access token을 받아 Authorization 헤더에 담아 보호된 서비스에 요청하려면 oauth2ClientId, oauth2ClientSecret, oauth2TokenEndpoint 프로퍼티를 사용해야 해요. 이 값들은 RFC 6749 명세대로 정의되고 Authorization Server가 제공하는 값이에요.

아래 예제에서 camel은 제공된 자격 증명(client id와 client secret)으로 [https://localhost:8080/realms/master/protocol/openid-connect/token](https://localhost:8080/realms/master/protocol/openid-connect/token)에 내부 요청을 보내고, 응답에서 access_token을 받은 뒤, [https://localhost:9090](https://localhost:9090)으로 이뤄질 요청의 Authorization 헤더에 그 토큰을 채워 넣어요.

from("direct:start")
  .to("https://localhost:9090/?oauth2ClientId=my-client-id&oauth2ClientSecret=my-client-secret&oauth2TokenEndpoint=https://localhost:8080/realms/master/protocol/openid-connect/token&oauth2Scope=my-scope");

<route>
  <from uri="direct:start"/>
  <to uri="https://localhost:9090/?oauth2ClientId=my-client-id&amp;oauth2ClientSecret=my-client-secret&amp;oauth2TokenEndpoint=https://localhost:8080/realms/master/protocol/openid-connect/token&amp;oauth2Scope=my-scope"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - to:
            uri: "https://localhost:9090/"
            parameters:
              oauth2ClientId: my-client-id
              oauth2ClientSecret: my-client-secret
              oauth2TokenEndpoint: "https://localhost:8080/realms/master/protocol/openid-connect/token"
              oauth2Scope: my-scope

OAuth2는 RFC 8707도 지원하는데, 이때는 본문에 _Resource Indicator_를 담아야 해요:

from("direct:start")
  .to("https://localhost:9090/?oauth2ClientId=my-client-id&oauth2ClientSecret=my-client-secret&oauth2TokenEndpoint=https://localhost:8080/realms/master/protocol/openid-connect/token&oauth2Scope=my-scope&oauth2ResourceIndicator=https://localhost:9090");

<route>
  <from uri="direct:start"/>
  <to uri="https://localhost:9090/?oauth2ClientId=my-client-id&amp;oauth2ClientSecret=my-client-secret&amp;oauth2TokenEndpoint=https://localhost:8080/realms/master/protocol/openid-connect/token&amp;oauth2Scope=my-scope&amp;oauth2ResourceIndicator=https://localhost:9090"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - to:
            uri: "https://localhost:9090/"
            parameters:
              oauth2ClientId: my-client-id
              oauth2ClientSecret: my-client-secret
              oauth2TokenEndpoint: "https://localhost:8080/realms/master/protocol/openid-connect/token"
              oauth2Scope: my-scope
              oauth2ResourceIndicator: "https://localhost:9090"

참고 Resource Indicator는 컴포넌트 URI에 정의된 실제 엔드포인트의 URL이에요.

참고 Camel은 OAuth2 client credentials 플로우만 지원해요

중요 Camel은 access token에 대해 어떤 검증도 하지 않아요. 검증은 하위 서비스의 몫이에요.

토큰 캐싱 (Caching tokens)

oauth2CacheTokens=true로 두면 Camel은 토큰이 만료될 때까지 캐시해요 (oauth2CachedTokensDefaultExpirySeconds, oauth2CachedTokensExpirationMarginSeconds 참고). oauth2CachedTokensKey 옵션이 어떤 요청들이 캐시된 토큰을 공유할지 결정해요:

HOST_ONLY (default): one token shared by all requests to the same scheme, host and port.
HOST_AND_PATH: one token per path. The query is not taken into account.
FULL_URI: one token per request URI, including the query (the behaviour before Camel 4.23).

client id, client secret, token endpoint, scope, resource indicator는 항상 키의 일부예요. 토큰 요청 자체는 요청 URI에 의존하지 않기 때문에, 기본값인 HOST_ONLY에서는 toD의 동적 경로나 쿼리처럼 URI가 새로 생겨도 매번 새 토큰을 요청하지 않아요.

from("direct:start")
  .toD("https://localhost:9090/event/${header.eventId}?oauth2ClientId=my-client-id&oauth2ClientSecret=my-client-secret&oauth2TokenEndpoint=https://localhost:8080/realms/master/protocol/openid-connect/token&oauth2CacheTokens=true&oauth2CachedTokensKey=HOST_ONLY");

<route>
  <from uri="direct:start"/>
  <toD uri="https://localhost:9090/event/${header.eventId}?oauth2ClientId=my-client-id&amp;oauth2ClientSecret=my-client-secret&amp;oauth2TokenEndpoint=https://localhost:8080/realms/master/protocol/openid-connect/token&amp;oauth2CacheTokens=true&amp;oauth2CachedTokensKey=HOST_ONLY"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - toD:
            uri: "https://localhost:9090/event/${header.eventId}"
            parameters:
              oauth2ClientId: my-client-id
              oauth2ClientSecret: my-client-secret
              oauth2TokenEndpoint: "https://localhost:8080/realms/master/protocol/openid-connect/token"
              oauth2CacheTokens: true
              oauth2CachedTokensKey: HOST_ONLY

다른 규칙이 필요하면 org.apache.camel.component.http.OAuth2CachedTokensKeyResolver를 구현하고 oauth2CachedTokensKeyResolver=#myResolver로 참조하세요. 이게 oauth2CachedTokensKey보다 우선하고, null을 돌려주면 해당 요청의 토큰은 캐시되지 않아요.

vault 기반 자격 증명 로테이션 (Vault-backed credential rotation)

vault 기반 프로퍼티 플레이스홀더(예: {{aws:mySecret/password}})를 DefaultContextReloadStrategy와 함께 쓰면, 각 reload 이벤트 후 Camel이 갱신된 컴포넌트 설정으로 모든 라우트와 엔드포인트를 다시 만들기 때문에 로테이션된 자격 증명이 자동으로 반영돼요. camel-http에는 별도 설정이 필요 없어요. 라우트 재시작 중에 새로 만들어지는 엔드포인트가 새로 해석된 자격 증명을 갖고 있거든요.

고급 사용법 (Advanced Usage)

HTTP producer를 더 세밀하게 제어하려면 HttpComponent를 사용하세요. 여러 클래스를 설정해 커스텀 동작을 만들 수 있어요.

HTTP Client에 SSL 설정 (Setting up SSL for HTTP Client)

JSSE Configuration Utility 사용하기

HTTP 컴포넌트는 Camel JSSE Configuration Utility로 SSL/TLS 설정을 지원해요. 이 유틸리티는 컴포넌트별로 써야 하는 코드의 양을 크게 줄여 주고, 엔드포인트와 컴포넌트 레벨에서 설정할 수 있어요. 다음 예제들은 HTTP 컴포넌트에서 이 유틸리티를 쓰는 방법을 보여 줘요.

컴포넌트의 프로그래밍 방식 설정

Java 전용: 프로그래밍 방식의 SSLContextParameters 설정

KeyStoreParameters ksp = new KeyStoreParameters();
ksp.setResource("file:/users/home/server/keystore.jks");
ksp.setPassword("keystorePassword");

KeyManagersParameters kmp = new KeyManagersParameters();
kmp.setKeyStore(ksp);
kmp.setKeyPassword("keyPassword");

SSLContextParameters scp = new SSLContextParameters();
scp.setKeyManagers(kmp);

HttpComponent httpComponent = getContext().getComponent("https", HttpComponent.class);
httpComponent.setSslContextParameters(scp);

Spring DSL 기반 엔드포인트 설정

XML 전용: Spring XML SSL context 파라미터와 엔드포인트 참조

  <camel:sslContextParameters
      id="sslContextParameters">
    <camel:keyManagers
        keyPassword="keyPassword">
      <camel:keyStore
          resource="file:/users/home/server/keystore.jks"
          password="keystorePassword"/>
    </camel:keyManagers>
  </camel:sslContextParameters>

  <to uri="https://127.0.0.1/mail/?sslContextParameters=#sslContextParameters"/>

Apache HTTP Client 직접 설정하기

기본적으로 camel-http 컴포넌트는 Apache HttpClient 위에서 만들어졌어요. 자세한 내용은 SSL/TLS customization을 참고하고(링크가 버전 4 관련 글을 가리키지만 여전히 어느 정도는 유효하고, 버전 5용 등문은 없어요), org.apache.camel.component.http.HttpsServerTestSupport 단위 테스트 기반 클래스도 살펴보세요. http client를 완전히 제어해야 한다면 커스텀 org.apache.camel.component.http.HttpClientConfigurer를 구현해서 http client를 설정하는 방법도 있어요.

다만 keystore와 truststore 만 지정하고 싶다면 Apache HTTP HttpClientConfigurer로 이렇게 할 수 있어요:

Java 전용: 프로그래밍 방식의 KeyStore와 SchemeRegistry 설정

KeyStore keystore = ...;
KeyStore truststore = ...;

SchemeRegistry registry = new SchemeRegistry();
registry.register(new Scheme("https", 443, new SSLSocketFactory(keystore, "mypassword", truststore)));

그다음 HttpClientConfigurer를 구현한 클래스를 만들어 위 예제처럼 keystore나 truststore를 제공하는 https 프로토콜을 등록해야 해요. 그런 다음 camel route builder 클래스에서 이렇게 연결하면 돼요:

Java 전용: 프로그래밍 방식의 HttpClientConfigurer 설정

HttpComponent httpComponent = getContext().getComponent("http", HttpComponent.class);
httpComponent.setHttpClientConfigurer(new MyHttpClientConfigurer());

Spring DSL로 이 작업을 한다면 URI로 HttpClientConfigurer를 지정할 수 있어요. 예를 들면:

XML 전용: `HttpClientConfigurer`의 Spring bean과 엔드포인트 참조

<bean id="myHttpClientConfigurer"
 class="my.https.HttpClientConfigurer">
</bean>

<to uri="https://myhostname.com:443/myURL?httpClientConfigurer=#myHttpClientConfigurer"/>

HttpClientConfigurer를 구현하고 위에서 설명한 대로 keystore와 truststore를 설정하기만 하면 잘 동작해요.

HTTPS 인증 시 주의할 점 (gotchas)

HTTPS 인증에서 문제를 겪었다는 최종 사용자 사례가 있어요. 결국 커스텀 설정을 갖춘 org.apache.hc.core5.http.protocol.HttpContext를 제공해서 해결됐죠:

1. HttpContexts용 (Spring) 팩토리를 만들어요:

Java 전용: preemptive basic 인증용 커스텀 HttpContext 팩토리

public class HttpContextFactory {

  private String httpHost = "localhost";
  private String httpPort = 9001;
  private String user = "some-user";
  private String password = "my-secret";

  private HttpClientContext context = HttpClientContext.create();
  private BasicAuthCache authCache = new BasicAuthCache();
  private BasicScheme basicAuth = new BasicScheme();

  public HttpContext getObject() {
    UsernamePasswordCredentials credentials = new UsernamePasswordCredentials(user, password.toCharArray());
    BasicCredentialsProvider provider = new BasicCredentialsProvider();
    HttpHost host = new HttpHost(httpHost, httpPort);
    provider.setCredentials(host, credentials);

    authCache.put(host, basicAuth);

    httpContext.setAuthCache(authCache);
    httpContext.setCredentialsProvider(provider);

    return httpContext;
  }

  // getter and setter
}

2. Spring application context 파일에 `HttpContext`를 선언해요:

XML 전용: HttpContext 팩토리의 Spring bean 선언

<bean id="myHttpContext" factory-bean="httpContextFactory" factory-method="getObject"/>

3. http URL에서 그 context를 참조해요:

XML 전용: HttpContext bean을 참조하는 엔드포인트 URI

<to uri="https://myhostname.com:443/myURL?httpContext=#myHttpContext"/>

다른 SSLContextParameters 사용하기

HTTP 컴포넌트는 컴포넌트당 org.apache.camel.support.jsse.SSLContextParameters 인스턴스를 하나만 지원해요. 서로 다른 인스턴스를 두 개 이상 써야 한다면 아래처럼 HTTP 컴포넌트를 여러 개 구성해야 해요. 여기서는 두 컴포넌트가 각자 자기만의 sslContextParameters 프로퍼티 인스턴스를 쓰고 있어요.

XML 전용: 서로 다른 SSL context를 쓰는 다중 HTTP 컴포넌트의 Spring bean 선언

<bean id="http-foo" class="org.apache.camel.component.http.HttpComponent">
   <property name="sslContextParameters" ref="sslContextParams1"/>
   <property name="x509HostnameVerifier" ref="hostnameVerifier"/>
</bean>

<bean id="http-bar" class="org.apache.camel.component.http.HttpComponent">
   <property name="sslContextParameters" ref="sslContextParams2"/>
   <property name="x509HostnameVerifier" ref="hostnameVerifier"/>
</bean>

Camel 메시지에서 http 프로토콜 헤더 제거 (Removing http protocol headers in the Camel Message)

Camel에는 http 프로토콜 헤더를 이용해 일을 처리하는 컴포넌트가 여럿 있어요.

camel-http, camel-jetty, camel-cxf 같은 컴포넌트들이 그렇죠.

이런 컴포넌트들을 사용한다면 HTTP 프로토콜 헤더에 주의를 기울여야 해요:

  Exchange.CONTENT_ENCODING
  Exchange.CONTENT_TYPE
  Exchange.HTTP_BASE_URI
  Exchange.HTTP_CHARACTER_ENCODING
  Exchange.HTTP_METHOD
  Exchange.HTTP_PATH
  Exchange.HTTP_QUERY
  Exchange.HTTP_RESPONSE_CODE

이 헤더들이 다른 엔드포인트를 방해하지 않게 하려면 Remove Headers EIP로 이렇게 제거하면 돼요:

from("jetty://http://myhost:9000/myservice/")
  .removeHeaders("CamelHttp*")
  .to("otherEndpoint");

<route>
  <from uri="jetty://http://myhost:9000/myservice/"/>
  <removeHeaders pattern="CamelHttp*" />
  <to uri="otherEndpoint"/>
</route>

- route:
    from:
      uri: jetty://http://myhost:9000/myservice/
      steps:
        - removeHeaders:
            pattern: "CamelHttp*"
        - to:
            uri: otherEndpoint

더 알아보기 (Learn more)

이 문서에서 다룬 옵션과 예제 외에도 더 깊이 들어가고 싶다면 Apache Camel 공식 문서의 HTTP 컴포넌트 페이지를 참고하세요. SSL/TLS 설정이나 프록시 구성은 camel-http가 기반으로 삼는 Apache HttpClient 5 문서도 함께 보면 좋아요. 그 외 URI 파라미터나 헤더 조합은 위의 옵션 표와 예제를 다시 훑어보는 게 가장 정확합니다.

HTTP 컴포넌트

본문

URI 형식 (URI Format)

옵션 설정 방법 (Configuring Options)

컴포넌트 옵션 설정 (Configuring Component Options)

엔드포인트 옵션 설정 (Configuring Endpoint Options)

컴포넌트 옵션 (Component Options)

엔드포인트 옵션 (Endpoint Options)

Path 파라미터 (Path Parameters)

Query 파라미터 (Query Parameters)

메시지 헤더 (Message Headers)

사용법 (Usage)

메시지 본문 (Message Body)

시스템 프로퍼티 사용 (Using System Properties)

응답 코드 (Response code)

HTTP 429 Too Many Requests 처리 (Handling HTTP 429 Too Many Requests)

예외 (Exceptions)

어떤 HTTP 메서드가 사용될까 (Which HTTP method will be used)

호출할 URI 설정 (Configuring URI to call)

URI 파라미터 설정 (Configuring URI Parameters)

HTTP producer에 http 메서드(GET/PATCH/POST/PUT/DELETE/HEAD/OPTIONS/TRACE) 지정하기 (How to set the http method (GET/PATCH/POST/PUT/DELETE/HEAD/OPTIONS/TRACE) to the HTTP producer)

클라이언트 타임아웃 사용 - SO_TIMEOUT (Using client timeout - SO_TIMEOUT)

프록시 설정 (Configuring a Proxy)

URI 밖에서 프록시 설정 (Using proxy settings outside of URI)

charset 설정 (Configuring charset)

scheduled poll 예제 (Example with scheduled poll)

엔드포인트 URI에서 온 URI 파라미터 (URI Parameters from the endpoint URI)

메시지에서 온 URI 파라미터 (URI Parameters from the Message)

응답 코드 가져오기 (Getting the Response Code)

Camel 파라미터로 Apache HTTP client의 특정 프로퍼티 정의 (Defining specific properties of Apache HTTP client via Camel parameters)

쿠키 끄기 (Disabling Cookies)

스트리밍 메시지 본문과 basic auth (Basic auth with the streaming message body)

OAuth2 지원 (OAuth2 Support)

토큰 캐싱 (Caching tokens)

vault 기반 자격 증명 로테이션 (Vault-backed credential rotation)

고급 사용법 (Advanced Usage)

HTTP Client에 SSL 설정 (Setting up SSL for HTTP Client)

Camel 메시지에서 http 프로토콜 헤더 제거 (Removing http protocol headers in the Camel Message)

더 알아보기 (Learn more)

함께 읽는 실무 이야기