AWS S3 스토리지 서비스

원문 보기 위키 갱신 2026.10.11

AWS S3 스토리지 서비스 (AWS S3 Storage Service)

AWS2 S3 컴포넌트는 Amazon S3 서비스에 객체를 저장하고 가져올 수 있게 해 줘요. Camel 3.2부터 제공됐고, producer와 consumer를 모두 지원합니다. region, accessKey/secretKey, moveAfterRead, multiPartUpload, streamingUploadMode 같은 다양한 옵션으로 버킷 연산을 세밀하게 제어할 수 있어요.

출처: 문서

본문

Camel 3.2부터 지원

producer와 consumer를 모두 지원해요

AWS2 S3 컴포넌트는 Amazon S3 서비스에 객체를 저장하고 가져오는 기능을 지원해요.

사전 준비 사항 (Prerequisites)

유효한 Amazon Web Services 개발자 계정이 있고 Amazon S3를 사용하도록 가입되어 있어야 해요. 자세한 내용은 Amazon S3에서 확인할 수 있어요.

URI 형식 (URI Format)

aws2-s3://bucketNameOrArn[?options]

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

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

?options=value&option2=value&…

옵션 설정 (Configuring Options)

Camel 컴포넌트는 두 단계로 나눠 설정해요:

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

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

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

예컨대 컴포넌트에는 보안 설정, 인증용 자격 증명, 네트워크 연결 URL 같은 것들이 들어갑니다.

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

컴포넌트를 설정하는 방법은 이렇게 있어요:

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

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

엔드포인트는 옵션이 많은 편이라 설정에 시간을 더 쓰게 돼요. 이 옵션들은 엔드포인트가 하고 싶은 동작을 맞춤 설정하는 데 도움을 줘요. 옵션은 엔드포인트가 컨슈머(from)로 쓰이는지, 프로듀서(to)로 쓰이는지, 둘 다인지에 따라 분류되기도 해요.

엔드포인트 설정은 대부분 엔드포인트 URI의 _path_와 query 파라미터로 직접 이뤄져요. Java에서 엔드포인트와 데이터 포맷을 _타입 세이프_하게 설정하고 싶다면 Endpoint DSL과 DataFormat DSL을 쓸 수도 있어요.

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

프로퍼티 플레이스홀더가 주는 이점은 이렇게 있어요:

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

지금부터 두 절에 걸쳐 모든 옵션을 나열해요. 먼저 컴포넌트 옵션이고, 그다음이 엔드포인트 옵션이에요.

컴포넌트 옵션 (Component Options)

AWS S3 Storage Service 컴포넌트는 아래 나열한 옵션들을 지원해요.

Name	Description	Default	Type
autoCreateBucket (common)	S3 버킷 bucketName을 자동 생성할지 설정해요. moveAfterRead 옵션이 켜진 경우에도 적용되고, destinationBucket이 아직 없으면 그 버킷도 생성해 줘요.	false	boolean
configuration (common)	컴포넌트 설정이에요.		AWS2S3Configuration
delimiter (common)	com.amazonaws.services.s3.model.ListObjectsRequest에서 관심 있는 객체만 소비하기 위해 쓰는 구분자예요.		String
forcePathStyle (common)	S3 클라이언트가 virtual-hosted-style 대신 path-style URL을 쓸지 설정해요.	false	boolean
ignoreBody (common)	true면 S3 객체 본문을 완전히 무시하고, false면 S3 객체를 본문에 넣어요. true로 설정하면 includeBody 옵션이 정의한 동작을 덮어써요.	false	boolean
overrideEndpoint (common)	엔드포인트를 오버라이드할지 설정해요. 이 옵션은 uriEndpointOverride 옵션과 함께 사용해야 해요.	false	boolean
pojoRequest (common)	POJO 요청을 본문으로 쓸지 여부예요.	false	boolean
policy (common)	com.amazonaws.services.s3.AmazonS3#setBucketPolicy() 메서드에서 설정할 이 큐(queue)의 정책이에요.		String
prefix (common)	com.amazonaws.services.s3.model.ListObjectsRequest에서 관심 있는 객체만 소비하기 위해 쓰는 접두사예요.		String
region (common)	S3 클라이언트가 동작할 리전이에요. 이 파라미터를 쓰면 설정에서 리전의 소문자 이름(예: ap-east-1)을 기대하고, Region.EU_WEST_1.id() 같은 이름을 사용해야 해요.

Enum values:

ap-south-2
ap-south-1
eu-south-1
eu-south-2
us-gov-east-1
me-central-1
il-central-1
ca-central-1
eu-central-1
us-iso-west-1
eu-central-2
eu-isoe-west-1
us-west-1
us-west-2
af-south-1
eu-north-1
eu-west-3
eu-west-2
eu-west-1
ap-northeast-3
ap-northeast-2
ap-northeast-1
me-south-1
sa-east-1
ap-east-1
cn-north-1
ca-west-1
us-gov-west-1
ap-southeast-1
ap-southeast-2
us-iso-east-1
ap-southeast-3
ap-southeast-4
us-east-1
us-east-2
cn-northwest-1
us-isob-east-1
aws-global
aws-cn-global
aws-us-gov-global
aws-iso-global
aws-iso-b-global

Enum values:

progressive
random
timestamp

Enum values:

copyObject
listObjects
deleteObject
deleteObjects
deleteBucket
listBuckets
getObject
getObjectRange
createDownloadLink
createUploadLink
headBucket
headObject
restoreObject
getObjectTagging
putObjectTagging
deleteObjectTagging
getObjectAcl
putObjectAcl
createBucket
getBucketTagging
putBucketTagging
deleteBucketTagging
getBucketVersioning
putBucketVersioning
getBucketPolicy
putBucketPolicy
deleteBucketPolicy

Enum values:

override
lastPart

Enum values:

HTTP
HTTPS

엔드포인트 옵션 (Endpoint Options)

AWS S3 Storage Service 엔드포인트는 다음 URI 문법으로 설정돼요:

aws2-s3://bucketNameOrArn

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

경로 파라미터 (Path Parameters)

Name	Description	Default	Type
bucketNameOrArn (common)	필수 버킷 이름 또는 ARN이에요.		String

쿼리 파라미터 (Query Parameters)

Name	Description	Default	Type
autoCreateBucket (common)	S3 버킷 bucketName을 자동 생성할지 설정해요. moveAfterRead 옵션이 켜진 경우에도 적용되고, destinationBucket이 아직 없으면 그 버킷도 생성해 줘요.	false	boolean
delimiter (common)	com.amazonaws.services.s3.model.ListObjectsRequest에서 관심 있는 객체만 소비하기 위해 쓰는 구분자예요.		String
forcePathStyle (common)	S3 클라이언트가 virtual-hosted-style 대신 path-style URL을 쓸지 설정해요.	false	boolean
ignoreBody (common)	true면 S3 객체 본문을 완전히 무시하고, false면 S3 객체를 본문에 넣어요. true로 설정하면 includeBody 옵션이 정의한 동작을 덮어써요.	false	boolean
overrideEndpoint (common)	엔드포인트를 오버라이드할지 설정해요. 이 옵션은 uriEndpointOverride 옵션과 함께 사용해야 해요.	false	boolean
pojoRequest (common)	POJO 요청을 본문으로 쓸지 여부예요.	false	boolean
policy (common)	com.amazonaws.services.s3.AmazonS3#setBucketPolicy() 메서드에서 설정할 이 큐(queue)의 정책이에요.		String
prefix (common)	com.amazonaws.services.s3.model.ListObjectsRequest에서 관심 있는 객체만 소비하기 위해 쓰는 접두사예요.		String
region (common)	S3 클라이언트가 동작할 리전이에요. 이 파라미터를 쓰면 설정에서 리전의 소문자 이름(예: ap-east-1)을 기대하고, Region.EU_WEST_1.id() 같은 이름을 사용해야 해요.

Enum values:

ap-south-2
ap-south-1
eu-south-1
eu-south-2
us-gov-east-1
me-central-1
il-central-1
ca-central-1
eu-central-1
us-iso-west-1
eu-central-2
eu-isoe-west-1
us-west-1
us-west-2
af-south-1
eu-north-1
eu-west-3
eu-west-2
eu-west-1
ap-northeast-3
ap-northeast-2
ap-northeast-1
me-south-1
sa-east-1
ap-east-1
cn-north-1
ca-west-1
us-gov-west-1
ap-southeast-1
ap-southeast-2
us-iso-east-1
ap-southeast-3
ap-southeast-4
us-east-1
us-east-2
cn-northwest-1
us-isob-east-1
aws-global
aws-cn-global
aws-us-gov-global
aws-iso-global
aws-iso-b-global

| | String | | uriEndpointOverride (common) | 오버라이드할 URI 엔드포인트예요. 이 옵션은 overrideEndpoint 옵션과 함께 사용해야 해요. | | String | | customerAlgorithm (common (advanced)) | CustomerKey를 켠 경우 사용할 고객 알고리즘이에요. | | String | | customerKeyId (common (advanced)) | CustomerKey를 켠 경우 사용할 고객 키의 ID예요. | | String | | customerKeyMD5 (common (advanced)) | CustomerKey를 켠 경우 사용할 고객 키의 MD5예요. | | String | | deleteAfterRead (consumer) | 객체를 가져온 뒤 S3에서 삭제해요. 삭제는 Exchange가 커밋될 때만 수행되고, 롤백이 일어나면 객체는 삭제되지 않아요. 이 옵션이 false면 폴링할 때마다 같은 객체가 계속 조회되니, 라우트에서 중복을 걸러내려면 Idempotent Consumer EIP를 써야 해요. AWS2S3Constants#BUCKET_NAME과 AWS2S3Constants#KEY 헤더로 필터링하거나, AWS2S3Constants#KEY 헤더만으로 필터링할 수 있어요. | true | boolean | | destinationBucket (consumer) | moveAfterRead가 true일 때 객체를 옮겨담을 대상 버킷이에요. | | String | | destinationBucketPrefix (consumer) | 객체를 옮길 때(moveAfterRead=true) 쓸 대상 버킷 접두사예요. | | String | | destinationBucketSuffix (consumer) | 객체를 옮길 때(moveAfterRead=true) 쓸 대상 버킷 접미사예요. | | String | | doneFileName (consumer) | 이 값을 주면 done 파일이 존재할 때만 파일을 소비해요. | | String | | fileName (consumer) | 지정한 파일 이름으로 버킷에서 객체를 가져와요. | | String | | includeBody (consumer) | true면 S3Object exchange를 소비해서 본문에 넣고 닫아요. false면 S3Object 스트림을 본문에 그대로 넣고, 헤더에는 S3 객체 메타데이터가 설정돼요. 이 옵션은 autocloseBody 옵션과 밀접하게 연관돼 있어요. includeBody를 true로 하면 S3Object 스트림을 소비하면서 함께 닫지만, false면 스트림을 닫는 건 호출자의 몫이에요. 다만 includeBody가 false일 때 autocloseBody를 true로 하면 exchange 완료 시점에 스트림을 자동으로 닫도록 예약해 줘요. | true | boolean | | includeFolders (consumer) | true면 폴더/디렉터리도 소비해요. false면 폴더는 무시되고 해당 Exchange는 만들어지지 않아요. | true | boolean | | maxConnections (consumer) | 지원 중단 S3 클라이언트 설정에서 maxConnections 파라미터를 지정해요. 이 옵션은 지원 중단됐고 효과가 없어요. HTTP 클라이언트 커넥션 풀을 커스터마이즈하려면 S3 클라이언트 설정의 httpClientBuilder 옵션을 쓰세요. | 60 | int | | maxMessagesPerPoll (consumer) | 각 폴링에서 가져올 메시지 수의 최대 한도예요. 기본값은 10이고, 0이나 음수로 두면 무제한이에요. | 10 | int | | moveAfterRead (consumer) | 객체를 가져온 뒤 다른 버킷으로 옮겨요. 이 동작을 하려면 destinationBucket 옵션을 설정해야 해요. 복사는 Exchange가 커밋될 때만 수행되고, 롤백이 일어나면 객체는 옮겨지지 않아요. | false | boolean | | removePrefixOnMove (consumer) | 복사하기 전에 새 S3Object 키에서 prefix 설정 문자열 내용을 제거해요. 예컨대 prefix가 'demo/notify'이고 destinationBucketPrefix가 'demo/archive'이면, 키가 'demo/notify/example.txt'인 S3Object는 'demo/archive/example.txt'로 복사돼요. 기본 동작이라면 새 키는 'demo/archive/demo/notify/example.txt'가 돼요. moveAfterRead가 true일 때만 적용돼요. | false | boolean | | sendEmptyMessageWhenIdle (consumer) | 폴링 컨슈머가 파일을 하나도 가져오지 못했을 때 이 옵션을 켜면 빈 메시지(본문 없음)를 대신 보내 줘요. | false | boolean | | autocloseBody (consumer (advanced)) | 이 옵션이 true이고 includeBody가 false이면 exchange 완료 시점에 S3Object.close() 메서드가 호출돼요. includeBody 옵션과 밀접하게 연관돼 있어요. includeBody를 false로, autocloseBody를 false로 두면 스트림을 닫는 건 호출자의 몫이고, autocloseBody를 true로 두면 S3Object 스트림을 자동으로 닫아 줘요. | true | boolean | | bridgeErrorHandler (consumer (advanced)) | 컨슈머를 Camel 라우팅 에러 핸들러에 연결(bridge)해요. 그러면 Camel 컨슈머가 들어오는 메시지를 가져오는 동안 발생한 예외도 (가능하면) 메시지로 처리돼서 라우팅 에러 핸들러가 다루게 돼요. 중요: 이 기능은 서드파티 컴포넌트가 예외가 던져졌을 때 Camel에 알려줄 수 있을 때만 가능해요. 일부 컴포넌트는 내부에서만 처리하기 때문에 bridgeErrorHandler를 쓸 수 없어요. 다른 경우에는 향후 릴리스에서 서드파티 컴포넌트에 연결(hook)되도록 Camel 컴포넌트를 개선할 수 있어요. 기본값으로 컨슈머는 org.apache.camel.spi.ExceptionHandler를 써서 예외를 WARN 또는 ERROR 레벨로 로깅하고 무시해요. | false | boolean | | exceptionHandler (consumer (advanced)) | 컨슈머가 커스텀 ExceptionHandler를 쓰게 해 줘요. bridgeErrorHandler 옵션이 켜져 있으면 이 옵션은 사용되지 않는다는 점에 유의하세요. 기본값으로 컨슈머는 예외를 WARN 또는 ERROR 레벨로 로깅하고 무시해요. | | ExceptionHandler | | exchangePattern (consumer (advanced)) | 컨슈머가 exchange를 만들 때 exchange 패턴을 설정해요.

Enum values:

InOnly
InOut

Enum values:

progressive
random
timestamp

Enum values:

copyObject
listObjects
deleteObject
deleteObjects
deleteBucket
listBuckets
getObject
getObjectRange
createDownloadLink
createUploadLink
headBucket
headObject
restoreObject
getObjectTagging
putObjectTagging
deleteObjectTagging
getObjectAcl
putObjectAcl
createBucket
getBucketTagging
putBucketTagging
deleteBucketTagging
getBucketVersioning
putBucketVersioning
getBucketPolicy
putBucketPolicy
deleteBucketPolicy

Enum values:

override
lastPart

Enum values:

HTTP
HTTPS

Enum values:

TRACE
DEBUG
INFO
WARN
ERROR
OFF

Enum values:

NANOSECONDS
MICROSECONDS
MILLISECONDS
SECONDS
MINUTES
HOURS
DAYS

메시지 헤더 (Message Headers)

AWS S3 Storage Service 컴포넌트는 다음과 같은 메시지 헤더들을 지원해요:

Name	Description	Type
CamelAwsS3BucketName (common) Constant: `BUCKET_NAME`	이 객체가 저장될 버킷 이름이에요(프로듀서에서 simple 언어로 동적 지정 가능). 현재 연산에 쓰이거나 이 객체가 담긴 버킷을 가리켜요.	String
CamelAwsS3ProducedBucketName (producer) Constant: `PRODUCED_BUCKET_NAME`	프로듀서가 s3 객체를 가져오거나 넣을 때 계산해서 쓴 버킷 이름이에요.	String
CamelAwsS3BucketDestinationName (producer) Constant: `BUCKET_DESTINATION_NAME`	현재 연산에 쓰일 대상 버킷 이름이에요.	String
CamelAwsS3BucketExists (common) Constant: `BUCKET_EXISTS`	headBucket 연산을 쓸 때 버킷이 존재하는지 여부예요.	boolean
CamelAwsS3ContentControl (common) Constant: `CACHE_CONTROL`	HTTP 요청/응답 체인에서 캐싱 동작을 지정할 수 있게 해 주는 선택적 Cache-Control HTTP 헤더예요.	String
CamelAwsS3ContentDisposition (common) Constant: `CONTENT_DISPOSITION`	객체를 저장할 때 추천 파일 이름 같은 표현 정보를 지정하는 선택적 Content-Disposition HTTP 헤더예요.	String
CamelAwsS3ContentEncoding (common) Constant: `CONTENT_ENCODING`	객체에 적용된 콘텐츠 인코딩과, Content-Type 필드가 가리키는 미디어 타입을 얻으려면 어떤 디코딩 메커니즘을 적용해야 하는지 지정하는 선택적 Content-Encoding HTTP 헤더예요.	String
CamelAwsS3ContentLength (common) Constant: `CONTENT_LENGTH`	연관된 객체의 크기를 바이트로 나타내는 Content-Length HTTP 헤더예요.	Long
CamelAwsS3ContentMD5 (common) Constant: `CONTENT_MD5`	RFC 1864에 따른 객체의 base64 인코딩 128비트 MD5 다이제스트예요(헤더는 제외한 콘텐츠). 이 데이터는 Amazon S3가 받은 데이터가 발신자가 보낸 데이터와 같은지 확인하는 메시지 무결성 검사로 쓰여요.	String
CamelAwsS3ContentType (common) Constant: `CONTENT_TYPE`	객체에 저장된 콘텐츠의 타입을 나타내는 Content-Type HTTP 헤더예요. 이 헤더 값은 표준 MIME 타입이에요.	String
CamelAwsS3ETag (common) Constant: `E_TAG`	(producer) 새로 업로드된 객체의 ETag 값이에요. (consumer) RFC 1864에 따른 객체의 16진수 인코딩 128비트 MD5 다이제스트예요. 이 데이터는 호출자가 받은 데이터가 Amazon S3가 보낸 데이터와 같은지 확인하는 무결성 검사로 쓰여요.	String
CamelAwsS3Key (common) Constant: `KEY`	이 객체가 저장되어 있거나 저장될 키예요(프로듀서에서 simple 언어로 동적 지정 가능). 현재 연산에 쓰이는 키이기도 해요.	String
CamelAwsS3ProducedKey (producer) Constant: `PRODUCED_KEY`	이 객체를 가져올 때 계산해서 쓴 키예요.	String
CamelAwsS3DestinationKey (producer) Constant: `DESTINATION_KEY`	현재 연산에 쓰일 대상 키예요.	String
CamelAwsS3LastModified (common) Constant: `LAST_MODIFIED`	Last-Modified 헤더의 값으로, Amazon S3가 연관된 객체의 마지막 수정을 기록한 날짜와 시각이에요.	Date
CamelAwsS3StorageClass (common) Constant: `STORAGE_CLASS`	이 객체의 스토리지 클래스예요.	String
CamelAwsS3VersionId (common) Constant: `VERSION_ID`	(producer) 새로 업로드된 객체의 선택적 버전 ID예요. (consumer) 있으면 연관된 Amazon S3 객체의 버전 ID예요. 버전 ID는 객체 버저닝이 켜진 Amazon S3 버킷에 객체를 업로드할 때만 할당돼요.	String
CamelAwsS3CannedAcl (producer) Constant: `CANNED_ACL`	객체에 적용될 canned ACL이에요. 허용 값은 software.amazon.awssdk.services.s3.model.ObjectCannedACL을 보세요.	String
CamelAwsS3Acl (producer) Constant: `ACL`	잘 구성된 Amazon S3 액세스 제어 목록(ACL) 객체예요.

Enum values:

private
public-read
public-read-write
authenticated-read
null

| | BucketCannedACL | | CamelAwsS3GrantFullControl (producer) Constant: GRANT_FULL_CONTROL | 피부여자(grantee)에게 객체에 대한 READ, READ_ACP, WRITE_ACP 권한을 줘요. 값은 id=, emailAddress=, uri= 같은 피부여자 표현식이에요. | | String | | CamelAwsS3GrantRead (producer) Constant: GRANT_READ | 피부여자가 객체 데이터와 메타데이터를 읽을 수 있게 해 줘요. 값은 id=, emailAddress=, uri= 같은 피부여자 표현식이에요. | | String | | CamelAwsS3GrantReadACP (producer) Constant: GRANT_READ_ACP | 피부여자가 객체 ACL을 읽을 수 있게 해 줘요. 값은 id=, emailAddress=, uri= 같은 피부여자 표현식이에요. | | String | | CamelAwsS3GrantWriteACP (producer) Constant: GRANT_WRITE_ACP | 피부여자가 객체의 ACL을 쓸 수 있게 해 줘요. 값은 id=, emailAddress=, uri= 같은 피부여자 표현식이에요. | | String | | CamelAwsS3Operation (common) Constant: S3_OPERATION | 수행할 연산이에요. 허용 값은 copyObject, deleteObject, listBuckets, deleteBucket, listObjects예요. | | String | | CamelAwsS3ServerSideEncryption (common) Constant: SERVER_SIDE_ENCRYPTION | AWS 관리 키로 객체를 암호화할 때 서버 사이드 암호화 알고리즘을 설정해요. 예컨대 AES256을 쓰세요. | | String | | CamelAwsS3ExpirationTime (consumer) Constant: EXPIRATION_TIME | 객체 만료가 설정되어 있으면(PUT Bucket lifecycle 참고) 응답이 이 헤더를 포함해요. | | String | | CamelAwsS3ReplicationStatus (consumer) Constant: REPLICATION_STATUS | 요청이 복제 규칙의 원본 또는 대상 버킷을 다루는 경우 Amazon S3가 이 값을 돌려줄 수 있어요.

Enum values:

COMPLETE
PENDING
FAILED
REPLICA
COMPLETED
null

| | ReplicationStatus | | CamelAwsS3RangeStart (producer) Constant: RANGE_START | 가져올 첫 바이트의 위치예요. | | String | | CamelAwsS3RangeEnd (producer) Constant: RANGE_END | 가져올 마지막 바이트의 위치예요. | | String | | CamelAwsS3DowloadLinkExpirationTime (producer) Constant: DOWNLOAD_LINK_EXPIRATION_TIME | 다운로드 링크의 만료 시간(밀리초)이에요. | | Long | | CamelAwsS3DownloadLinkBrowserCompatible (producer) Constant: DOWNLOAD_LINK_BROWSER_COMPATIBLE | 다운로드 링크가 브라우저 호환인지 여부예요. | | boolean | | CamelAwsS3DownloadLinkHttpRequestHeaders (producer) Constant: DOWNLOAD_LINK_HTTP_REQUEST_HEADERS | 서비스가 필요로 하는 헤더예요(BrowserCompatible이 true면 필요 없어요). | | Map | | CamelAwsS3DownloadLinkSignedPayload (producer) Constant: DOWNLOAD_LINK_SIGNED_PAYLOAD | 서비스가 필요로 하는 요청 페이로드예요(BrowserCompatible이 true면 필요 없어요). | | String | | CamelAwsS3Metadata (common) Constant: METADATA | S3에서 객체와 함께 저장하거나 저장된 메타데이터 맵이에요. 메타데이터에 대한 자세한 내용은 https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.htmlhere를 보세요. | | Map | | CamelMessageTimestamp (consumer) Constant: MESSAGE_TIMESTAMP | 메시지의 타임스탬프예요. | | long | | CamelAwsS3Prefix (common) Constant: PREFIX | com.amazonaws.services.s3.model.ListObjectsRequest에서 관심 있는 객체만 나열하기 위해 쓰는 접두사예요. | | | | CamelAwsS3Delimiter (common) Constant: DELIMITER | com.amazonaws.services.s3.model.ListObjectsRequest에서 관심 있는 객체만 나열하기 위해 쓰는 구분자예요. | | String | | CamelAwsS3IfMatchCondition (common) Constant: IF_MATCH_CONDITION | 엔티티 태그(ETag)가 이 헤더에 지정한 것과 같을 때만 객체를 돌려주거나 복사해요. | | String | | CamelAwsS3IfModifiedSinceCondition (common) Constant: IF_MODIFIED_SINCE_CONDITION | 지정한 시간 이후에 수정되었을 때만 객체를 돌려주거나 복사하고, 그렇지 않으면 304 Not Modified 오류를 돌려줘요. | | String | | CamelAwsS3IfNoneMatchCondition (common) Constant: IF_NONE_MATCH_CONDITION | 엔티티 태그(ETag)가 이 헤더에 지정한 것과 다를 때만 객체를 돌려주거나 복사해요. | | String | | CamelAwsS3IfUnmodifiedSinceCondition (common) Constant: IF_UNMODIFIED_SINCE_CONDITION | 지정한 시간 이후에 수정되지 않았을 때만 객체를 돌려주거나 복사해요. | | String | | CamelAwsS3OverrideBucketName (common) Constant: OVERRIDE_BUCKET_NAME | 덮어쓸 버킷 이름이에요(프로듀서에서 simple 언어로 동적 지정 가능). 이 객체가 저장되거나 현재 연산에 쓰이거나 이 객체가 담긴 버킷을 가리켜요. | | String | | CamelAwsS3KeysToDelete (producer) Constant: KEYS_TO_DELETE | deleteObjects 연산을 쓸 때 삭제할 키 목록이에요. | | List | | CamelAwsS3RestoreDays (producer) Constant: RESTORE_DAYS | restoreObject 연산을 쓸 때 복원 요청이 활성 상태로 유지될 일수예요. | | Integer | | CamelAwsS3RestoreTier (producer) Constant: RESTORE_TIER | restoreObject 연산을 쓸 때 복원이 처리될 등급이에요(예: Standard, Bulk, Expedited). | | String | | CamelAwsS3ObjectTags (producer) Constant: OBJECT_TAGS | putObjectTagging 연산을 쓸 때 설정할 객체 태그예요. | | Map | | CamelAwsS3BucketTags (producer) Constant: BUCKET_TAGS | putBucketTagging 연산을 쓸 때 설정할 버킷 태그예요. | | Map | | CamelAwsS3BucketPolicy (producer) Constant: BUCKET_POLICY | putBucketPolicy 연산을 쓸 때 JSON 문자열로 주는 버킷 정책이에요. | | String | | CamelAwsS3VersioningStatus (producer) Constant: VERSIONING_STATUS | putBucketVersioning 연산을 쓸 때의 버저닝 상태예요(Enabled 또는 Suspended). | | String | | CamelAwsS3MfaDelete (producer) Constant: MFA_DELETE | putBucketVersioning 연산을 쓸 때 MFA 삭제를 켤지 여부예요. | | String | | CamelAwsS3UploadLinkExpirationTime (producer) Constant: UPLOAD_LINK_EXPIRATION_TIME | 업로드 링크의 만료 시간(밀리초)이에요. | | Long | | CamelAwsS3UploadLinkBrowserCompatible (producer) Constant: UPLOAD_LINK_BROWSER_COMPATIBLE | 업로드 링크가 브라우저 호환인지 여부예요. | | boolean | | CamelAwsS3UploadLinkHttpRequestHeaders (producer) Constant: UPLOAD_LINK_HTTP_REQUEST_HEADERS | 업로드를 위해 서비스가 필요로 하는 헤더예요(BrowserCompatible이 true면 필요 없어요). | | Map | | CamelAwsS3UploadLinkSignedPayload (producer) Constant: UPLOAD_LINK_SIGNED_PAYLOAD | 업로드를 위해 서비스가 필요로 하는 요청 페이로드예요(BrowserCompatible이 true면 필요 없어요). | | String |

필수 S3 컴포넌트 옵션

Amazon S3에 접근하려면 레지스트리에 amazonS3Client를 제공하거나 accessKey와 secretKey를 제공해야 해요.

사용법 (Usage)

배치 컨슈머 (Batch Consumer)

이 컴포넌트는 Batch Consumer를 구현해요.

덕분에 예컨대 이 배치에 메시지가 몇 개 있는지 알 수 있고, 그 수만큼 메시지를 Aggregator로 취합하게 할 수도 있어요.

S3 프로듀서 연산 (S3 Producer operations)

Camel-AWS2-S3 컴포넌트는 프로듀서 쪽에서 다음 연산을 제공해요:

copyObject
deleteObject
deleteObjects
listBuckets
deleteBucket
listObjects
getObject (이 연산은 S3Object 인스턴스를 돌려줘요)
getObjectRange (이 연산은 S3Object 인스턴스를 돌려줘요)
createDownloadLink
createUploadLink
headBucket
headObject
restoreObject
getObjectTagging
putObjectTagging
deleteObjectTagging
getObjectAcl
putObjectAcl
createBucket
getBucketTagging
putBucketTagging
deleteBucketTagging
getBucketVersioning
putBucketVersioning
getBucketPolicy
putBucketPolicy
deleteBucketPolicy

연산을 명시적으로 지정하지 않으면 프로듀서는 이렇게 동작해요:

단일 파일 업로드
multiPartUpload 옵션이 켜져 있으면 multipart 업로드

예시 (Examples)

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

Java
XML
YAML

from("aws2-s3://helloBucket?accessKey=yourAccessKey&secretKey=yourSecretKey&prefix=hello.txt")
    .to("file:/var/downloaded");

<route>
  <from uri="aws2-s3://helloBucket?accessKey=yourAccessKey&amp;secretKey=yourSecretKey&amp;prefix=hello.txt"/>
  <to uri="file:/var/downloaded"/>
</route>

- route:
    from:
      uri: aws2-s3://helloBucket
      parameters:
        accessKey: yourAccessKey
        secretKey: yourSecretKey
        prefix: hello.txt
      steps:
        - to:
            uri: file:/var/downloaded

고급 AmazonS3 설정 (Advanced AmazonS3 configuration)

Camel 애플리케이션이 방화벽 뒤에서 돌거나 S3Client 인스턴스 설정을 더 세밀하게 제어하고 싶다면, 직접 인스턴스를 만들어서 Camel aws2-s3 컴포넌트 설정에서 참조할 수 있어요:

Java
XML
YAML

from("aws2-s3://MyBucket?amazonS3Client=#client&delay=5000&maxMessagesPerPoll=5")
    .to("mock:result");

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

- route:
    from:
      uri: aws2-s3://MyBucket
      parameters:
        amazonS3Client: "#client"
        delay: 5000
        maxMessagesPerPoll: 5
      steps:
        - to:
            uri: mock:result

S3 컴포넌트에서 KMS 사용하기 (Use KMS with the S3 component)

AWS 인프라를 활용해 AWS KMS로 데이터를 암호화/복호화하려면, 2.21.x에서 도입된 옵션을 다음 예제처럼 쓸 수 있어요

Java
XML
YAML

from("file:tmp/test?fileName=test.txt")
    .setHeader("CamelAwsS3Key", constant("testFile"))
    .to("aws2-s3://mybucket?amazonS3Client=#client&useAwsKMS=true&awsKMSKeyId=3f0637ad-296a-3dfe-a796-e60654fb128c");

<route>
  <from uri="file:tmp/test?fileName=test.txt"/>
  <setHeader name="CamelAwsS3Key">
    <constant>testFile</constant>
  </setHeader>
  <to uri="aws2-s3://mybucket?amazonS3Client=#client&amp;useAwsKMS=true&amp;awsKMSKeyId=3f0637ad-296a-3dfe-a796-e60654fb128c"/>
</route>

- route:
    from:
      uri: file:tmp/test
      parameters:
        fileName: test.txt
      steps:
        - setHeader:
            name: CamelAwsS3Key
            constant: testFile
        - to:
            uri: aws2-s3://mybucket
            parameters:
              amazonS3Client: "#client"
              useAwsKMS: true
              awsKMSKeyId: "3f0637ad-296a-3dfe-a796-e60654fb128c"

팁 Java 예제는 "CamelAwsS3Key" 문자열 값을 직접 써요. Java 상수 AWS2S3Constants.KEY를 쓸 수도 있어요.

이렇게 하면 S3에게 KMS 키 3f0637ad-296a-3dfe-a796-e60654fb128c를 써서 test.txt 파일을 암호화하라고 요청하는 거예요. 이 파일을 내려받으라고 하면 복호화는 다운로드 직전에 바로 진행돼요.

정적 자격 증명, 기본 자격 증명 공급자, 프로필 자격 증명 공급자 (Static credentials, Default Credential Provider and Profile Credentials Provider)

useDefaultCredentialsProvider 옵션을 지정하고 true로 설정하면 명시적인 정적 자격 증명 사용을 피할 수 있어요.

기본 자격 증명 공급자(Default Credentials Provider)의 평가 순서는 다음과 같아요:

Java 시스템 프로퍼티 - aws.accessKeyId와 aws.secretKey.
환경 변수 - AWS_ACCESS_KEY_ID와 AWS_SECRET_ACCESS_KEY.
AWS STS의 Web Identity Token.
공유 자격 증명 및 설정 파일.
Amazon ECS 컨테이너 자격 증명 - 환경 변수 AWS_CONTAINER_CREDENTIALS_RELATIVE_URI가 설정되어 있으면 Amazon ECS에서 읽어 와요.
Amazon EC2 인스턴스 프로필 자격 증명.

useProfileCredentialsProvider 옵션을 true로, profileCredentialsName을 프로필 이름으로 지정해서 프로필 자격 증명 공급자(Profile Credentials Provider)를 쓸 수도 있어요.

정적, 기본, 프로필 자격 증명 중 한 번에 하나만 쓸 수 있어요.

자세한 내용은 AWS 자격 증명 문서를 참고하세요.

버킷 자동 생성 (Bucket Auto-creation)

autoCreateBucket 옵션으로 사용자는 버킷이 없을 때 S3 버킷 자동 생성을 피할 수 있어요. 이 옵션의 기본값은 false예요. false로 두면 AWS에서 존재하지 않는 버킷에 대한 연산은 성공하지 않고 오류가 돌아와요.

버킷에서 다른 버킷으로 내용 옮기기 (Moving stuff between a bucket and another bucket)

어떤 사용자는 이 컴포넌트의 copyObject 기능을 쓰지 않고, 한 버킷에서 내용을 소비해서 다른 버킷으로 옮기고 싶어 해요. 그런 경우라면 컨슈머 exchange로 들어온 bucketName 헤더를 제거하는 걸 잊지 마세요. 안 그러면 파일이 계속 같은 원래 버킷에 덮어써져요.

고객 키를 암호화에 사용하기 (Using the customer key as encryption)

KMS를 쓰는 대안으로 고객 키(customer key) 지원도 도입했어요. 다음 코드가 예시예요.

Java 전용: 프로그래밍 방식의 고객 키 암호화 설정

String key = UUID.randomUUID().toString();
byte[] secretKey = generateSecretKey();
String b64Key = Base64.getEncoder().encodeToString(secretKey);
String b64KeyMd5 = Md5Utils.md5AsBase64(secretKey);

String awsEndpoint = "aws2-s3://mycamel?autoCreateBucket=false&useCustomerKey=true&customerKeyId=RAW(" + b64Key + ")&customerKeyMD5=RAW(" + b64KeyMd5 + ")&customerAlgorithm=" + AES256.name();

from("direct:putObject")
    .setHeader("CamelAwsS3Key", constant("test.txt"))
    .setBody(constant("Test"))
    .to(awsEndpoint);

POJO를 본문으로 사용하기 (Using a POJO as body)

옵션이 여러 개라서 AWS 요청을 만드는 게 복잡할 때가 있어요. 그래서 POJO를 본문으로 쓸 수 있는 방법을 도입했어요. AWS S3에서는 제출할 수 있는 연산이 여러 가지인데, 예컨대 List objects 요청이라면 이렇게 할 수 있어요:

Java 전용: POJO 요청은 AWS SDK 요청 객체를 직접 만들어야 해요

from("direct:aws2-s3")
    .setBody(ListObjectsV2Request.builder().bucket(bucketName).build())
    .to("aws2-s3://test?amazonS3Client=#amazonS3Client&operation=listObjects&pojoRequest=true");

이렇게 하면 이 연산과 관련된 헤더나 옵션을 따로 넘기지 않고도 요청을 바로 전달할 수 있어요.

S3 클라이언트 만들고 레지스트리에 컴포넌트 추가하기 (Create S3 client and add component to registry)

AWS2S3Configuration으로 고급 설정을 하고 싶을 때가 있어요. 이 설정 객체는 S3 클라이언트를 지정하는 것도 허용해요. 다음 예제처럼 컴포넌트 설정에서 S3 클라이언트를 만들고 지정할 수 있어요

Java 전용: 프로그래밍 방식의 S3 클라이언트 생성

String awsBucketAccessKey = "your_access_key";
String awsBucketSecretKey = "your_secret_key";

S3Client s3Client = S3Client.builder()
        .credentialsProvider(StaticCredentialsProvider.create(
                AwsBasicCredentials.create(awsBucketAccessKey, awsBucketSecretKey)))
        .region(Region.US_EAST_1).build();

AWS2S3Configuration configuration = new AWS2S3Configuration();
configuration.setAmazonS3Client(s3Client);
configuration.setAutoDiscoverClient(true);
configuration.setBucketName("s3bucket2020");
configuration.setRegion("us-east-1");

이제 (위에서 만든 설정 객체로) S3 컴포넌트를 구성하고, 라우트 초기화 전에 configure 메서드에서 레지스트리에 추가할 수 있어요.

Java 전용: 프로그래밍 방식의 컴포넌트 등록

AWS2S3Component s3Component = new AWS2S3Component(getContext());
s3Component.setConfiguration(configuration);
s3Component.setLazyStartProducer(true);
camelContext.addComponent("aws2-s3", s3Component);

이제 이 컴포넌트가 camel 라우트에 구현된 모든 연산에 쓰여요.

Dell ECS (Elastic Cloud Solutions)에 객체를 저장하고 가져올 때 참고 사항

Dell ECS에 객체를 저장하고 가져오려면 forcePathStyle과 overrideEndpoint 옵션 둘 다 true로 설정하고, uriEndpointOverride로 자기만의 ECS 엔드포인트를 제공해야 해요.

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

String awsBucketAccessKey = "your_access_key";
String awsBucketSecretKey = "your_secret_key";

S3Client s3Client = S3Client.builder()
        .credentialsProvider(StaticCredentialsProvider.create(
                AwsBasicCredentials.create(awsBucketAccessKey, awsBucketSecretKey)))
        .region(Region.US_EAST_1).build();

AWS2S3Configuration configuration = new AWS2S3Configuration();
configuration.setForcePathStyle(true);
configuration.setOverrideEndpoint(true);
configuration.setUriEndpointOverride("http://ecs1.emc.com:9020");

자세한 내용은 Dell 문서를 보세요.

하위 페이지 (Sub-Pages)

특정 기능에 대한 자세한 내용은 다음을 보세요:

Producer Operations - 최소 IAM 권한을 갖춘 모든 프로듀서 연산 예제
Streaming Upload - 스트리밍 업로드 모드, 네이밍 전략, 타임스탬프 그룹화
Consumer Examples - 접두사 필터링, 폴링 전략, done 파일을 포함한 컨슈머 패턴

의존성 (Dependencies)

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

pom.xml

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-aws2-s3</artifactId>
    <version>${camel-version}</version>
</dependency>

여기서 ${camel-version}은 실제 Camel 버전으로 바꿔야 해요.

더 알아보기 (Learn more)

Producer Operations, Streaming Upload, Consumer Examples 하위 문서에서 연산별 예제, 스트리밍 업로드, 컨슈머 패턴을 더 깊게 살펴보세요.
AWS 자격 증명 구성이 고민된다면 위의 정적/기본/프로필 자격 증명 섹션과 AWS 자격 증명 문서를 먼저 확인하세요.
Dell ECS 같은 S3 호환 스토리지 연결은 forcePathStyle·overrideEndpoint·uriEndpointOverride 조합이 핵심이라 위의 Dell ECS 섹션 예제를 참고하세요.

AWS S3 스토리지 서비스