IBM Cloud Object Storage

원문 보기 위키 갱신 2026.10.11

IBM Cloud Object Storage (IBM COS)

IBM COS 컴포넌트는 IBM Cloud Object Storage에 객체를 저장하고 가져올 수 있게 해 주는 컴포넌트예요. Camel 4.16부터 제공됐고 producer와 consumer를 모두 지원하며, 버킷 자동 생성, 멀티파트 업로드, 읽은 뒤 이동 같은 옵션과 apiKey/serviceInstanceId/endpointUrl 기반 인증을 제공해요.

출처: 문서

본문

Camel 4.16부터 지원

producer와 consumer를 모두 지원해요

IBM COS 컴포넌트는 IBM Cloud Object Storage에 객체를 저장하고 가져오는 기능을 지원해요.

준비물 (Prerequisites)

유효한 IBM Cloud 계정이 있고 IBM Cloud Object Storage를 사용하도록 가입되어 있어야 해요. 자세한 정보는 IBM Cloud Object Storage에서 확인할 수 있습니다.

URI 형식 (URI Format)

ibm-cos://bucketName[?options]

버킷이 아직 없으면 자동으로 만들어져요.

다음 형식으로 URI에 쿼리 옵션을 붙일 수 있어요:

?options=value&option2=value&…

옵션 설정 방법 (Configuring Options)

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

컴포넌트(component) 레벨
엔드포인트(endpoint) 레벨

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

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

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

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

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

the Component DSL.
설정 파일(application.properties, *.yaml 파일 등).
Java 코드에서 직접.

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

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

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

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

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

URL, 포트 번호, 민감한 정보 같은 설정을 하드코딩하는 걸 막아 줘요.
설정을 코드 밖으로 분리할 수 있어요.
코드가 더 유연해지고 재사용하기 좋아져요.

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

컴포넌트 옵션 (Component Options)

IBM Cloud Object Storage 컴포넌트가 지원하는 옵션은 아래와 같아요.

Name	Description	Default	Type
autoCreateBucket (common)	버킷이 없으면 자동으로 만들어요.	false	boolean
configuration (common)	컴포넌트 설정이에요.		IBMCOSConfiguration
delimiter (common)	객체를 나열할 때 사용할 구분자예요.		String
endpointUrl (common)	IBM COS 엔드포인트 URL(예: https://s3.us-south.cloud-object-storage.appdomain.cloud). 일부 연산은 크로스 리전 엔드포인트 대신 리전 엔드포인트 URL을 써야 한다는 점에 유의하세요.		String
location (common)	IBM COS 위치/리전(예: us-south, eu-gb)이에요.		String
prefix (common)	객체를 나열할 때 사용할 접두어예요.		String
bridgeErrorHandler (consumer)	consumer를 Camel 라우팅 에러 핸들러로 브리지할 수 있게 해 줘요. 그러면 Camel consumer가 들어오는 메시지를 가져오는 동안 발생한 예외를(가능한 경우) 메시지로 처리해 라우팅 에러 핸들러가 맡게 할 수 있어요. 중요: 이 기능은 서드파티 컴포넌트가 예외 발생을 Camel에 알릴 수 있을 때만 가능해요. 어떤 컴포넌트는 내부에서만 처리하기 때문에 bridgeErrorHandler를 쓸 수 없어요. 다른 상황에서는 Camel 컴포넌트를 개선해서 서드파티 컴포넌트에 후킹해 이를 가능하게 만들 수도 있어요. 기본으로 consumer는 org.apache.camel.spi.ExceptionHandler로 예외를 처리하고, WARN 또는 ERROR 레벨로 로그를 남긴 뒤 무시해요.	false	boolean
deleteAfterRead (consumer)	객체를 가져온 뒤 IBM COS에서 삭제해요.	true	boolean
destinationBucket (consumer)	객체를 이동시킬 대상 버킷이에요.		String
destinationBucketPrefix (consumer)	대상 버킷의 객체에 붙일 접두어예요.		String
destinationBucketSuffix (consumer)	대상 버킷의 객체에 붙일 접미어예요.		String
fileName (consumer)	지정한 파일 이름으로 버킷에서 객체를 가져와요.		String
includeBody (consumer)	exchange에 객체 본문을 포함해요.	true	boolean
includeFolders (consumer)	객체를 나열할 때 폴더/디렉터리도 포함해요.	true	boolean
moveAfterRead (consumer)	객체를 가져온 뒤 다른 버킷으로 이동시켜요.	false	boolean
autocloseBody (consumer (advanced))	처리가 끝난 뒤 객체 입력 스트림을 자동으로 닫을지 여부예요.	true	boolean
deleteAfterWrite (producer)	업로드한 뒤 로컬 파일시스템에서 객체를 삭제해요.	false	boolean
keyName (producer)	객체의 키 이름이에요.		String
lazyStartProducer (producer)	producer를 lazy(첫 메시지 시점)로 시작할지 여부예요. lazy 시작을 쓰면 producer가 시작 중 실패해서 라우트 시작이 실패하는 상황에서도 CamelContext와 라우트를 시작할 수 있고, 시작 실패 처리를 Camel의 라우팅 에러 핸들러로 넘길 수 있어요. 다만 첫 메시지를 처리하는 시점에 producer를 만들고 시작하는 데 시간이 조금 걸려서 전체 처리 시간이 길어질 수 있다는 점은 유의하세요.	false	boolean
multiPartUpload (producer)	큰 파일에 멀티파트 업로드를 사용해요.	false	boolean
operation (producer)
수행할 연산이에요.

Enum values:

copyObject
listObjects
deleteObject
deleteObjects
deleteBucket
listBuckets
getObject
getObjectRange
headBucket
createBucket
putObject

엔드포인트 옵션 (Endpoint Options)

IBM Cloud Object Storage 엔드포인트는 다음 URI 구문으로 설정해요:

ibm-cos:bucketName

다음 _path_와 query 파라미터를 쓸 수 있어요:

경로 파라미터 (Path Parameters)

Name	Description	Default	Type
bucketName (common)	필수 버킷 이름이에요.		String

쿼리 파라미터 (Query Parameters)

Name	Description	Default	Type
autoCreateBucket (common)	버킷이 없으면 자동으로 만들어요.	false	boolean
delimiter (common)	객체를 나열할 때 사용할 구분자예요.		String
endpointUrl (common)	IBM COS 엔드포인트 URL(예: https://s3.us-south.cloud-object-storage.appdomain.cloud). 일부 연산은 크로스 리전 엔드포인트 대신 리전 엔드포인트 URL을 써야 한다는 점에 유의하세요.		String
location (common)	IBM COS 위치/리전(예: us-south, eu-gb)이에요.		String
prefix (common)	객체를 나열할 때 사용할 접두어예요.		String
deleteAfterRead (consumer)	객체를 가져온 뒤 IBM COS에서 삭제해요.	true	boolean
destinationBucket (consumer)	객체를 이동시킬 대상 버킷이에요.		String
destinationBucketPrefix (consumer)	대상 버킷의 객체에 붙일 접두어예요.		String
destinationBucketSuffix (consumer)	대상 버킷의 객체에 붙일 접미어예요.		String
fileName (consumer)	지정한 파일 이름으로 버킷에서 객체를 가져와요.		String
includeBody (consumer)	exchange에 객체 본문을 포함해요.	true	boolean
includeFolders (consumer)	객체를 나열할 때 폴더/디렉터리도 포함해요.	true	boolean
maxMessagesPerPoll (consumer)	폴링 한 번당 가져올 메시지 최대 개수 제한이에요.	10	int
moveAfterRead (consumer)	객체를 가져온 뒤 다른 버킷으로 이동시켜요.	false	boolean
sendEmptyMessageWhenIdle (consumer)	폴링 consumer가 파일을 하나도 가져오지 못했을 때 이 옵션을 켜면 대신 빈 메시지(본문 없음)를 보내요.	false	boolean
autocloseBody (consumer (advanced))	처리가 끝난 뒤 객체 입력 스트림을 자동으로 닫을지 여부예요.	true	boolean
bridgeErrorHandler (consumer (advanced))	consumer를 Camel 라우팅 에러 핸들러로 브리지할 수 있게 해 줘요. 그러면 Camel consumer가 들어오는 메시지를 가져오는 동안 발생한 예외를(가능한 경우) 메시지로 처리해 라우팅 에러 핸들러가 맡게 할 수 있어요. 중요: 이 기능은 서드파티 컴포넌트가 예외 발생을 Camel에 알릴 수 있을 때만 가능해요. 어떤 컴포넌트는 내부에서만 처리하기 때문에 bridgeErrorHandler를 쓸 수 없어요. 다른 상황에서는 Camel 컴포넌트를 개선해서 서드파티 컴포넌트에 후킹해 이를 가능하게 만들 수도 있어요. 기본으로 consumer는 org.apache.camel.spi.ExceptionHandler로 예외를 처리하고, WARN 또는 ERROR 레벨로 로그를 남긴 뒤 무시해요.	false	boolean
exceptionHandler (consumer (advanced))	consumer가 커스텀 ExceptionHandler를 쓰게 할 수 있어요. bridgeErrorHandler 옵션이 켜져 있으면 이 옵션은 사용되지 않는다는 점에 유의하세요. 기본으로 consumer는 예외를 직접 처리하고, WARN 또는 ERROR 레벨로 로그를 남긴 뒤 무시해요.		ExceptionHandler
exchangePattern (consumer (advanced))
consumer가 exchange를 만들 때 교환 패턴을 설정해요.

Enum values:

InOnly
InOut

수행할 연산이에요.

Enum values:

copyObject
listObjects
deleteObject
deleteObjects
deleteBucket
listBuckets
getObject
getObjectRange
headBucket
createBucket
putObject

consumer는 폴링할 때 시작/완료 로그 한 줄을 남겨요. 이 옵션으로 그 로깅 레벨을 설정할 수 있어요.

Enum values:

TRACE
DEBUG
INFO
WARN
ERROR
OFF

initialDelay와 delay 옵션의 시간 단위예요.

Enum values:

NANOSECONDS
MICROSECONDS
MILLISECONDS
SECONDS
MINUTES
HOURS
DAYS

메시지 헤더 (Message Headers)

IBM Cloud Object Storage 컴포넌트가 지원하는 메시지 헤더는 아래와 같아요:

Name	Description	Type
CamelIBMCOSBucketName (common) Constant: `BUCKET_NAME`	이 객체가 저장될 버킷 이름, 또는 현재 연산에 사용될 버킷 이름이에요.	String
CamelIBMCOSBucketDestinationName (producer) Constant: `BUCKET_DESTINATION_NAME`	현재 연산에 사용될 대상 버킷 이름이에요.	String
CamelIBMCOSCacheControl (common) Constant: `CACHE_CONTROL`	캐싱 동작을 지정할 수 있게 해 주는 선택적 Cache-Control HTTP 헤더예요.	String
CamelIBMCOSContentDisposition (common) Constant: `CONTENT_DISPOSITION`	권장 파일 이름 같은 표현 정보를 지정하는 선택적 Content-Disposition HTTP 헤더예요.	String
CamelIBMCOSContentEncoding (common) Constant: `CONTENT_ENCODING`	객체에 적용된 콘텐츠 인코딩을 나타내는 선택적 Content-Encoding HTTP 헤더예요.	String
CamelIBMCOSContentLength (common) Constant: `CONTENT_LENGTH`	연관 객체의 크기를 바이트 단위로 나타내는 Content-Length HTTP 헤더예요.	Long
CamelIBMCOSContentMD5 (common) Constant: `CONTENT_MD5`	연관 객체의 base64 인코딩된 128비트 MD5 다이제스트예요.	String
CamelIBMCOSContentType (common) Constant: `CONTENT_TYPE`	연관 객체에 저장된 콘텐츠 타입을 나타내는 Content-Type HTTP 헤더예요.	String
CamelIBMCOSETag (common) Constant: `E_TAG`	객체의 ETag 값이에요.	String
CamelIBMCOSKey (common) Constant: `KEY`	이 객체가 저장돼 있거나 저장될 키예요.	String
CamelIBMCOSDestinationKey (producer) Constant: `DESTINATION_KEY`	현재 연산에 사용될 대상 키예요.	String
CamelIBMCOSLastModified (common) Constant: `LAST_MODIFIED`	IBM COS가 객체에 마지막 수정을 기록한 날짜와 시각을 나타내는 Last-Modified 헤더 값이에요.	Date
CamelIBMCOSVersionId (common) Constant: `VERSION_ID`	가능하면 연관 IBM COS 객체의 버전 ID예요.	String
CamelIBMCOSOperation (common) Constant: `COS_OPERATION`	수행할 연산이에요.	String
CamelIBMCOSPrefix (common) Constant: `PREFIX`	객체를 필터링할 때 사용하는 접두어예요.	String
CamelIBMCOSDelimiter (common) Constant: `DELIMITER`	객체를 필터링할 때 사용하는 구분자예요.	String
CamelIBMCOSKeysToDelete (producer) Constant: `KEYS_TO_DELETE`	deleteObjects 연산을 사용할 때 삭제할 키 목록이에요.	List
CamelIBMCOSMetadata (common) Constant: `METADATA`	IBM COS에 객체와 함께 저장할 메타데이터 맵이에요.	Map
CamelIBMCOSRangeStart (producer) Constant: `RANGE_START`	객체 일부를 가져올 때의 범위 시작 위치예요.	Long
CamelIBMCOSRangeEnd (producer) Constant: `RANGE_END`	객체 일부를 가져올 때의 범위 끝 위치예요.	Long
CamelIBMCOSBucketExists (producer) Constant: `BUCKET_EXISTS`	버킷이 존재하는지 여부예요.	Boolean

필수 IBM COS 컴포넌트 옵션 (Required IBM COS component options)

IBM Cloud Object Storage에 접근하려면 리전에 맞는 endpointUrl과 함께 apiKey와 serviceInstanceId를 제공해야 해요.

사용법 (Usage)

배치 consumer (Batch Consumer)

이 컴포넌트는 배치 consumer를 구현해요.

예를 들어 이 배치에 메시지가 몇 개 있는지 알 수 있고, Aggregator가 그 개수만큼 메시지를 모으게 할 수 있어요.

IBM COS producer 연산 (IBM COS Producer operations)

IBM COS 컴포넌트는 producer 쪽에서 다음 연산을 제공해요:

copyObject
createBucket
deleteBucket
deleteObject
deleteObjects
getObject (InputStream을 반환해요)
getObjectRange (일부 콘텐츠가 담긴 InputStream을 반환해요)
headBucket
listBuckets
listObjects
putObject

연산을 명시하지 않으면 producer는 이렇게 동작해요:

단일 파일 업로드
multiPartUpload 옵션이 켜져 있으면 멀티파트 업로드

예제 (Examples)

예를 들어 helloBucket 버킷에서 hello.txt 파일을 읽으려면 다음 스니펫을 쓰면 돼요:

Java
XML
YAML

from("ibm-cos://helloBucket?apiKey=yourApiKey&serviceInstanceId=yourServiceInstanceId&endpointUrl=https://s3.us-south.cloud-object-storage.appdomain.cloud&prefix=hello.txt")
  .to("file:/var/downloaded");

<route>
  <from uri="ibm-cos://helloBucket?apiKey=yourApiKey&amp;serviceInstanceId=yourServiceInstanceId&amp;endpointUrl=https://s3.us-south.cloud-object-storage.appdomain.cloud&amp;prefix=hello.txt"/>
  <to uri="file:/var/downloaded"/>
</route>

- route:
    from:
      uri: ibm-cos://helloBucket
      parameters:
        apiKey: yourApiKey
        serviceInstanceId: yourServiceInstanceId
        endpointUrl: "https://s3.us-south.cloud-object-storage.appdomain.cloud"
        prefix: hello.txt
      steps:
        - to:
            uri: file:/var/downloaded

고급 IBM COS 클라이언트 설정 (Advanced IBM COS Client configuration)

Camel 애플리케이션이 방화벽 뒤에서 돌아가거나 AmazonS3 클라이언트 인스턴스 설정을 더 세밀하게 제어해야 한다면, 직접 인스턴스를 만들고 Camel ibm-cos 컴포넌트 설정에서 참조할 수 있어요:

Java
XML
YAML

from("ibm-cos://MyBucket?cosClient=#client&delay=5000&maxMessagesPerPoll=5")
.to("mock:result");

<route>
  <from uri="ibm-cos://MyBucket?cosClient=#client&amp;delay=5000&amp;maxMessagesPerPoll=5"/>
  <to uri="mock:result"/>
</route>

- route:
    from:
      uri: ibm-cos://MyBucket
      parameters:
        cosClient: "#client"
        delay: 5000
        maxMessagesPerPoll: 5
      steps:
        - to:
            uri: mock:result

IBM COS 인증 (IBM COS Authentication)

IBM Cloud Object Storage는 인증에 IBM Cloud IAM(Identity and Access Management)을 사용해요. 다음을 제공해야 해요:

apiKey: 여러분의 IBM Cloud API 키
serviceInstanceId: COS 서비스 인스턴스 ID(CRN - Cloud Resource Name)
endpointUrl: 리전에 맞는 엔드포인트 URL(예: [https://s3.us-south.cloud-object-storage.appdomain.cloud](https://s3.us-south.cloud-object-storage.appdomain.cloud))

서비스 인스턴스 ID는 IBM Cloud 콘솔에서 찾을 수 있고, API 키도 콘솔에서 만들 수 있어요.

IBM COS 인증에 대한 자세한 내용은 IBM COS IAM 문서를 참고하세요.

IBM COS 엔드포인트 (IBM COS Endpoints)

IBM COS는 리전과 접속 유형(public, private, direct)별로 다른 엔드포인트를 제공해요. 예시:

퍼블릭 엔드포인트(US South): [https://s3.us-south.cloud-object-storage.appdomain.cloud](https://s3.us-south.cloud-object-storage.appdomain.cloud)
퍼블릭 엔드포인트(EU GB): [https://s3.eu-gb.cloud-object-storage.appdomain.cloud](https://s3.eu-gb.cloud-object-storage.appdomain.cloud)
프라이빗 엔드포인트(US South): [https://s3.private.us-south.cloud-object-storage.appdomain.cloud](https://s3.private.us-south.cloud-object-storage.appdomain.cloud)

엔드포인트 전체 목록은 IBM COS 엔드포인트 문서를 참고하세요.

크로스 리전 엔드포인트와 달리 리전 엔드포인트가 필요한 연산이 여럿 있다는 점에 유의하세요.

IBM COS producer 연산 예제 (IBM COS Producer Operation examples)

단일 업로드(Single Upload): 이 연산은 본문 내용을 기반으로 파일을 IBM COS에 업로드해요
Java
XML
YAML

from("direct:start")
    .setHeader("CamelIBMCOSKey", constant("camel.txt"))
    .setBody(constant("Camel rocks!"))
    .to("ibm-cos://mycamelbucket?apiKey=RAW(myApiKey)&serviceInstanceId=RAW(myServiceInstanceId)&endpointUrl=https://s3.us-south.cloud-object-storage.appdomain.cloud")
    .to("mock:result");

<route>
  <from uri="direct:start"/>
  <setHeader name="CamelIBMCOSKey">
    <constant>camel.txt</constant>
  </setHeader>
  <setBody>
    <constant>Camel rocks!</constant>
  </setBody>
  <to uri="ibm-cos://mycamelbucket?apiKey=RAW(myApiKey)&amp;serviceInstanceId=RAW(myServiceInstanceId)&amp;endpointUrl=https://s3.us-south.cloud-object-storage.appdomain.cloud"/>
  <to uri="mock:result"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - setHeader:
            name: CamelIBMCOSKey
            constant: camel.txt
        - setBody:
            constant: "Camel rocks!"
        - to:
            uri: ibm-cos://mycamelbucket
            parameters:
              apiKey: RAW(myApiKey)
              serviceInstanceId: RAW(myServiceInstanceId)
              endpointUrl: "https://s3.us-south.cloud-object-storage.appdomain.cloud"
        - to:
            uri: mock:result

이 연산은 mycamelbucket 버킷에 "Camel rocks!" 내용을 담은 camel.txt 파일을 업로드해요.

참고 API 키 같은 민감한 값은 프로퍼티 플레이스홀더 치환을 막으려고 RAW() 래퍼를 사용하세요.

멀티파트 업로드(Multipart Upload): 이 연산은 본문 내용을 기반으로 파일을 IBM COS에 멀티파트 업로드해요

Java 전용: 본문으로 Java File 객체가 필요해요

from("direct:start")
    .setHeader("CamelIBMCOSKey", constant("largefile.zip"))
    .process(exchange -> exchange.getIn().setBody(new File("src/largefile.zip")))
    .to("ibm-cos://mycamelbucket?cosClient=#cosClient&multiPartUpload=true&partSize=5242880")
    .to("mock:result");

이 연산은 mycamelbucket 버킷에 largefile.zip 파일을 파트 크기 5MB로 멀티파트 업로드해요.

CopyObject: 이 연산은 객체를 한 버킷에서 다른 버킷으로 복사해요
Java
XML
YAML

from("direct:start")
    .setHeader("CamelIBMCOSBucketDestinationName", constant("camelDestinationBucket"))
    .setHeader("CamelIBMCOSKey", constant("camelKey"))
    .setHeader("CamelIBMCOSDestinationKey", constant("camelDestinationKey"))
    .to("ibm-cos://mycamelbucket?cosClient=#cosClient&operation=copyObject")
    .to("mock:result");

<route>
  <from uri="direct:start"/>
  <setHeader name="CamelIBMCOSBucketDestinationName">
    <constant>camelDestinationBucket</constant>
  </setHeader>
  <setHeader name="CamelIBMCOSKey">
    <constant>camelKey</constant>
  </setHeader>
  <setHeader name="CamelIBMCOSDestinationKey">
    <constant>camelDestinationKey</constant>
  </setHeader>
  <to uri="ibm-cos://mycamelbucket?cosClient=#cosClient&amp;operation=copyObject"/>
  <to uri="mock:result"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - setHeader:
            name: CamelIBMCOSBucketDestinationName
            constant: camelDestinationBucket
        - setHeader:
            name: CamelIBMCOSKey
            constant: camelKey
        - setHeader:
            name: CamelIBMCOSDestinationKey
            constant: camelDestinationKey
        - to:
            uri: ibm-cos://mycamelbucket
            parameters:
              cosClient: "#cosClient"
              operation: copyObject
        - to:
            uri: mock:result

이 연산은 mycamelbucket 버킷에서 camelKey 헤더로 지정한 이름의 객체를 camelDestinationBucket 버킷의 camelDestinationKey로 복사해요.

DeleteObject: 이 연산은 버킷에서 객체를 삭제해요
Java
XML
YAML

from("direct:start")
    .setHeader("CamelIBMCOSKey", constant("camelKey"))
    .to("ibm-cos://mycamelbucket?cosClient=#cosClient&operation=deleteObject")
    .to("mock:result");

<route>
  <from uri="direct:start"/>
  <setHeader name="CamelIBMCOSKey">
    <constant>camelKey</constant>
  </setHeader>
  <to uri="ibm-cos://mycamelbucket?cosClient=#cosClient&amp;operation=deleteObject"/>
  <to uri="mock:result"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - setHeader:
            name: CamelIBMCOSKey
            constant: camelKey
        - to:
            uri: ibm-cos://mycamelbucket
            parameters:
              cosClient: "#cosClient"
              operation: deleteObject
        - to:
            uri: mock:result

이 연산은 mycamelbucket 버킷에서 camelKey 객체를 삭제해요.

DeleteObjects: 이 연산은 한 번의 요청으로 버킷에서 여러 객체를 삭제해요

Java 전용: 삭제할 키로 Java List가 필요해요

from("direct:start")
    .process(exchange -> {
        List<String> keys = Arrays.asList("file1.txt", "file2.txt", "file3.txt");
        exchange.getIn().setHeader("CamelIBMCOSKeysToDelete", keys);
    })
    .to("ibm-cos://mycamelbucket?cosClient=#cosClient&operation=deleteObjects")
    .to("mock:result");

이 연산은 한 번의 배치 요청으로 mycamelbucket 버킷에서 file1.txt, file2.txt, file3.txt 객체를 삭제해요.

ListBuckets: 이 연산은 이 리전에서 이 계정의 버킷 목록을 조회해요
Java
XML
YAML

from("direct:start")
  .to("ibm-cos://mycamelbucket?cosClient=#cosClient&operation=listBuckets")
  .to("mock:result");

<route>
  <from uri="direct:start"/>
  <to uri="ibm-cos://mycamelbucket?cosClient=#cosClient&amp;operation=listBuckets"/>
  <to uri="mock:result"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - to:
            uri: ibm-cos://mycamelbucket
            parameters:
              cosClient: "#cosClient"
              operation: listBuckets
        - to:
            uri: mock:result

이 연산은 이 계정의 버킷 목록을 조회해요.

DeleteBucket: 이 연산은 URI 파라미터나 헤더로 지정한 버킷을 삭제해요
Java
XML
YAML

from("direct:start")
  .to("ibm-cos://mycamelbucket?cosClient=#cosClient&operation=deleteBucket")
  .to("mock:result");

<route>
  <from uri="direct:start"/>
  <to uri="ibm-cos://mycamelbucket?cosClient=#cosClient&amp;operation=deleteBucket"/>
  <to uri="mock:result"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - to:
            uri: ibm-cos://mycamelbucket
            parameters:
              cosClient: "#cosClient"
              operation: deleteBucket
        - to:
            uri: mock:result

이 연산은 mycamelbucket 버킷을 삭제해요.

CreateBucket: 이 연산은 새 버킷을 만들어요
Java
XML
YAML

from("direct:start")
    .setHeader("CamelIBMCOSBucketName", constant("newBucket"))
    .to("ibm-cos://mycamelbucket?cosClient=#cosClient&operation=createBucket")
    .to("mock:result");

<route>
  <from uri="direct:start"/>
  <setHeader name="CamelIBMCOSBucketName">
    <constant>newBucket</constant>
  </setHeader>
  <to uri="ibm-cos://mycamelbucket?cosClient=#cosClient&amp;operation=createBucket"/>
  <to uri="mock:result"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - setHeader:
            name: CamelIBMCOSBucketName
            constant: newBucket
        - to:
            uri: ibm-cos://mycamelbucket
            parameters:
              cosClient: "#cosClient"
              operation: createBucket
        - to:
            uri: mock:result

이 연산은 _newBucket_이라는 이름의 새 버킷을 만들어요.

ListObjects: 이 연산은 특정 버킷의 객체 목록을 조회해요
Java
XML
YAML

from("direct:start")
  .to("ibm-cos://mycamelbucket?cosClient=#cosClient&operation=listObjects")
  .to("mock:result");

<route>
  <from uri="direct:start"/>
  <to uri="ibm-cos://mycamelbucket?cosClient=#cosClient&amp;operation=listObjects"/>
  <to uri="mock:result"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - to:
            uri: ibm-cos://mycamelbucket
            parameters:
              cosClient: "#cosClient"
              operation: listObjects
        - to:
            uri: mock:result

이 연산은 mycamelbucket 버킷의 객체 목록을 조회해요.

접두어가 있는 ListObjects(ListObjects with prefix): 이 연산은 접두어 필터와 함께 특정 버킷의 객체 목록을 조회해요
Java
XML
YAML

from("direct:start")
    .setHeader("CamelIBMCOSPrefix", constant("backup/"))
    .to("ibm-cos://mycamelbucket?cosClient=#cosClient&operation=listObjects")
    .to("mock:result");

<route>
  <from uri="direct:start"/>
  <setHeader name="CamelIBMCOSPrefix">
    <constant>backup/</constant>
  </setHeader>
  <to uri="ibm-cos://mycamelbucket?cosClient=#cosClient&amp;operation=listObjects"/>
  <to uri="mock:result"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - setHeader:
            name: CamelIBMCOSPrefix
            constant: "backup/"
        - to:
            uri: ibm-cos://mycamelbucket
            parameters:
              cosClient: "#cosClient"
              operation: listObjects
        - to:
            uri: mock:result

이 연산은 mycamelbucket 버킷에서 "backup/"으로 시작하는 객체만 조회해요.

GetObject: 이 연산은 특정 버킷에서 객체 하나를 가져와요
Java
XML
YAML

from("direct:start")
    .setHeader("CamelIBMCOSKey", constant("camelKey"))
    .to("ibm-cos://mycamelbucket?cosClient=#cosClient&operation=getObject")
    .to("mock:result");

<route>
  <from uri="direct:start"/>
  <setHeader name="CamelIBMCOSKey">
    <constant>camelKey</constant>
  </setHeader>
  <to uri="ibm-cos://mycamelbucket?cosClient=#cosClient&amp;operation=getObject"/>
  <to uri="mock:result"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - setHeader:
            name: CamelIBMCOSKey
            constant: camelKey
        - to:
            uri: ibm-cos://mycamelbucket
            parameters:
              cosClient: "#cosClient"
              operation: getObject
        - to:
            uri: mock:result

이 연산은 mycamelbucket 버킷의 camelKey 객체 내용을 담은 InputStream을 반환해요.

GetObjectRange: 이 연산은 특정 버킷에서 객체의 일부 범위를 가져와요
Java
XML
YAML

from("direct:start")
    .setHeader("CamelIBMCOSKey", constant("camelKey"))
    .setHeader("CamelIBMCOSRangeStart", constant(0L))
    .setHeader("CamelIBMCOSRangeEnd", constant(9L))
    .to("ibm-cos://mycamelbucket?cosClient=#cosClient&operation=getObjectRange")
    .to("mock:result");

<route>
  <from uri="direct:start"/>
  <setHeader name="CamelIBMCOSKey">
    <constant>camelKey</constant>
  </setHeader>
  <setHeader name="CamelIBMCOSRangeStart">
    <constant resultType="java.lang.Long">0</constant>
  </setHeader>
  <setHeader name="CamelIBMCOSRangeEnd">
    <constant resultType="java.lang.Long">9</constant>
  </setHeader>
  <to uri="ibm-cos://mycamelbucket?cosClient=#cosClient&amp;operation=getObjectRange"/>
  <to uri="mock:result"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - setHeader:
            name: CamelIBMCOSKey
            constant: camelKey
        - setHeader:
            name: CamelIBMCOSRangeStart
            constant: 0
        - setHeader:
            name: CamelIBMCOSRangeEnd
            constant: 9
        - to:
            uri: ibm-cos://mycamelbucket
            parameters:
              cosClient: "#cosClient"
              operation: getObjectRange
        - to:
            uri: mock:result

이 연산은 mycamelbucket 버킷의 camelKey 객체 내용 중 0부터 9까지 바이트를 담은 InputStream을 반환해요.

HeadBucket: 이 연산은 버킷이 존재하고 접근 권한이 있는지 확인해요
Java
XML
YAML

from("direct:start")
  .to("ibm-cos://mycamelbucket?cosClient=#cosClient&operation=headBucket")
  .to("mock:result");

<route>
  <from uri="direct:start"/>
  <to uri="ibm-cos://mycamelbucket?cosClient=#cosClient&amp;operation=headBucket"/>
  <to uri="mock:result"/>
</route>

- route:
    from:
      uri: direct:start
      steps:
        - to:
            uri: ibm-cos://mycamelbucket
            parameters:
              cosClient: "#cosClient"
              operation: headBucket
        - to:
            uri: mock:result

이 연산은 mycamelbucket 버킷이 존재하고 접근 가능한지 확인해요. 결과(true/false)는 메시지 본문에 담겨요.

IBM COS 컨슈머 (IBM COS Consumer)

IBM COS consumer는 버킷을 폴링해서 새 객체를 찾아 처리해요.

Java
XML
YAML

from("ibm-cos://mycamelbucket?cosClient=#cosClient&delay=5000&maxMessagesPerPoll=10&deleteAfterRead=true")
  .to("file:/var/downloaded");

<route>
  <from uri="ibm-cos://mycamelbucket?cosClient=#cosClient&amp;delay=5000&amp;maxMessagesPerPoll=10&amp;deleteAfterRead=true"/>
  <to uri="file:/var/downloaded"/>
</route>

- route:
    from:
      uri: ibm-cos://mycamelbucket
      parameters:
        cosClient: "#cosClient"
        delay: 5000
        maxMessagesPerPoll: 10
        deleteAfterRead: true
      steps:
        - to:
            uri: file:/var/downloaded

이 라우트는 mycamelbucket 버킷을 5초마다 폴링하고, 폴링 한 번당 최대 10개 객체를 처리하며, 처리가 성공적으로 끝난 객체는 삭제해요.

읽은 뒤 이동 (Move After Read)

읽은 뒤 객체를 삭제하는 대신, 다른 버킷이나 접두어로 이동시킬 수 있어요:

Java
XML
YAML

from("ibm-cos://mycamelbucket?cosClient=#cosClient&deleteAfterRead=false&moveAfterRead=true&destinationBucket=processed-bucket&destinationBucketPrefix=done-")
  .to("direct:process");

<route>
  <from uri="ibm-cos://mycamelbucket?cosClient=#cosClient&amp;deleteAfterRead=false&amp;moveAfterRead=true&amp;destinationBucket=processed-bucket&amp;destinationBucketPrefix=done-"/>
  <to uri="direct:process"/>
</route>

- route:
    from:
      uri: ibm-cos://mycamelbucket
      parameters:
        cosClient: "#cosClient"
        deleteAfterRead: false
        moveAfterRead: true
        destinationBucket: processed-bucket
        destinationBucketPrefix: "done-"
      steps:
        - to:
            uri: direct:process

이 라우트는 처리된 객체를 _mycamelbucket_에서 _processed-bucket_으로 옮기면서 각 객체 키 앞에 "done-"을 붙여요.

접두어 필터가 있는 IBM COS consumer (IBM COS Consumer with prefix filter)

접두어를 사용해서 소비할 객체를 걸러낼 수 있어요:

Java
XML
YAML

from("ibm-cos://mycamelbucket?cosClient=#cosClient&prefix=inbox/&deleteAfterRead=true")
  .to("direct:process");

<route>
  <from uri="ibm-cos://mycamelbucket?cosClient=#cosClient&amp;prefix=inbox/&amp;deleteAfterRead=true"/>
  <to uri="direct:process"/>
</route>

- route:
    from:
      uri: ibm-cos://mycamelbucket
      parameters:
        cosClient: "#cosClient"
        prefix: "inbox/"
        deleteAfterRead: true
      steps:
        - to:
            uri: direct:process

이 라우트는 키가 "inbox/"로 시작하는 객체만 소비해요.

통합 테스트 실행 (Running Integration Tests)

통합 테스트에는 유효한 IBM Cloud 자격 증명이 필요해요. 다음 단계에 따라 테스트를 준비하고 실행하세요.

서비스 자격 증명 만들기 (Creating Service Credentials)

IBM Cloud 콘솔에 로그인해요
Cloud Object Storage 인스턴스로 이동해요(없으면 새로 만들어요)
왼쪽 메뉴에서 Service credentials로 가요
New credential을 클릭해요
이름을 붙여요(예: camel-cos-test)
중요: 역할을 Manager로 설정해요(버킷 생성 연산에 필요해요)
Add를 클릭해요
새로 만든 자격 증명을 펼쳐 JSON을 확인해요

자격 증명을 테스트 프로퍼티에 매핑 (Mapping Credentials to Test Properties)

서비스 자격 증명 JSON에서 다음 값을 추출해요:

System Property	JSON Field	Example
`camel.ibm.cos.apiKey`	`apikey`	`Hh1u4wjecZ_jUhJScOt0sN…`
`camel.ibm.cos.serviceInstanceId`	`resource_instance_id`	`crn:v1:bluemix:public:cloud-object-storage:global:a/…`
`camel.ibm.cos.endpointUrl`	자격 증명에 없음 - 리전에 따라 선택	`[https://s3.us-south.cloud-object-storage.appdomain.cloud](https://s3.us-south.cloud-object-storage.appdomain.cloud)`

참고 자격 증명 JSON의 endpoints 필드는 컨트롤 API URL이지 실제 COS 엔드포인트가 아니에요. IBM COS 엔드포인트 문서에서 리전 엔드포인트를 골라야 해요.

테스트 실행 (Running the Tests)

mvn verify -pl components/camel-ibm/camel-ibm-cos \
  -Dcamel.ibm.cos.apiKey=YOUR_API_KEY \
  -Dcamel.ibm.cos.serviceInstanceId='YOUR_SERVICE_INSTANCE_ID' \
  -Dcamel.ibm.cos.endpointUrl=https://s3.us-south.cloud-object-storage.appdomain.cloud

팁 CRN의 특수 문자가 셸에 의해 해석되지 않도록 serviceInstanceId 값은 작은따옴표로 감싸세요.

문제 해결 (Troubleshooting)

403 Forbidden: 서비스 자격 증명에 Manager 역할이 있는지 확인하세요. 버킷 생성에는 Writer 역할로는 부족해요.

의존성 (Dependencies)

Maven 사용자라면 pom.xml에 다음 의존성을 추가해야 해요.

pom.xml

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

x.x.x는 Camel 버전 숫자예요.

더 알아보기 (Learn more)

IBM COS 인증과 엔드포인트는 IBM COS IAM 문서와 IBM COS 엔드포인트 문서에서 더 볼 수 있어요.
컴포넌트/엔드포인트 설정 방식은 Component DSL과 Property Placeholders 문서를 참고하세요.

IBM Cloud Object Storage