Azure Files

원문 보기 위키 갱신 2026.10.11

Azure Files (camel-azure-files)

Azure Files 컴포넌트는 Azure Storage의 Azure Files(파일 공유)에 접근해서 파일을 읽고 쓸 수 있게 해 주는 컴포넌트예요. Camel 3.22부터 제공됐고 producer와 consumer를 모두 지원합니다. FTP 컴포넌트를 본떠 만들어서 파일 컴포넌트 계열의 익숙한 옵션들이 대부분 그대로 동작해요.

출처: 문서

본문

Camel 3.22부터 지원

producer와 consumer 모두 지원

이 컴포넌트는 Azure Files에 대한 접근을 제공해요.

주의 (Caution) 프리뷰 컴포넌트라서 이후 릴리스에서 무엇이든 바뀔 수 있어요(기능과 동작이 공지 없이 변경되거나 수정되거나 아예 빠질 수도 있습니다). 동시에 어느 정도 안정화돼 있고, 문서는 적은 편이지만 몇몇 사용자는 자기 환경에서 잘 동작한다고 보고했고, 더 넓은 피드백을 받을 준비가 되어 있어요.

원격 파일 서버에서 파일을 소비할 때는 아래쪽에 있는 Consuming Files 섹션을 꼭 읽어 보세요. 파일 소비와 관련된 세부 내용이 거기 있어요.

Maven 사용자라면 이 컴포넌트를 쓰려고 pom.xml에 다음 의존성을 추가해야 해요:

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

엔드포인트 URI 형식 (Endpoint URI Format)

azure-files://account[.file.core.windows.net][:port]/share[/directory]

여기서 directory는 실제 작업 대상 디렉터리를 나타내요. directory는 상대 경로이고 share 이름은 포함하지 않아요. 상대 경로에는 inbox/spam처럼 중첩된 폴더가 들어갈 수 있고, 기본값은 share 루트 디렉터리예요.

autoCreate 옵션은 directory에 대해 지원돼요. consumer나 producer가 시작할 때 엔드포인트에 설정된 디렉터리를 만드는 추가 작업이 수행돼요. autoCreate의 기본값은 true예요. 반면 share는 반드시 미리 존재해야 하고 자동으로 만들어지지 않아요.

port 번호를 지정하지 않으면 Camel이 프로토콜에 맞는 기본값을 넣어 줘요(https면 443).

URI에는 쿼리 옵션을 ?option=value&option2=value&… 형식으로 붙일 수 있어요.

이 컴포넌트를 사용하려면 필요한 Azure 인증 정보를 제공하는 방법이 여러 가지 있어요:

Azure Identity를 쓰는 방법: credentialType=AZURE_IDENTITY를 지정하고 필요한 환경 변수를 제공해요. 이 방식이면 시크릿/인증서 기반 서비스 프린시펄(예: 앱 등록) 인증과 사용자 이름·비밀번호 인증도 가능해요.
공유 스토리지 계정 키를 쓰는 방법: credentialType=SHARED_ACCOUNT_KEY를 지정하고 Azure 계정의 sharedKey를 제공해요. 시작하기에 가장 간단한 방법이에요. sharedKey는 Azure 포털에서 생성할 수 있어요.
Azure SAS를 쓰는 방법: credentialType=AZURE_SAS를 지정하고 token 파라미터로 SAS 토큰 값을 넘겨요.

옵션 설정 (Configuring Options)

Camel 컴포넌트는 서로 다른 두 단계로 설정해요:

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

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

컴포넌트 레벨에서는 일반적이고 공유되는 설정을 지정하고, 이 설정은 엔드포인트들이 물려받아요. 가장 상위의 설정 단계예요.

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

컴포넌트에 따라 옵션이 몇 개뿐인 경우도 있고 많은 경우도 있어요. 컴포넌트는 보통 널리 쓰이는 기본값을 미리 갖추고 있어서, 컴포넌트에 설정할 옵션이 몇 개뿐이거나 아예 없을 때도 많아요.

컴포넌트를 설정하는 방법은 다음과 같아요:

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

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

엔드포인트는 옵션이 많아서 설정에 시간을 더 쓰게 돼요. 이 옵션들로 엔드포인트가 어떻게 동작할지 원하는 대로 조정할 수 있어요. 옵션은 엔드포인트를 consumer(from)로 쓰는지, producer(to)로 쓰는지, 둘 다 쓰는지에 따라 분류되기도 해요.

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

옵션을 설정할 때 좋은 습관은 프로퍼티 플레이스홀더를 쓰는 거예요.

플레이스홀더를 쓰면 이런 점이 좋아요:

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

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

컴포넌트 옵션 (Component Options)

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

Name	Description	Default	Type
bridgeErrorHandler (consumer)	consumer를 Camel 라우팅 에러 핸들러(routing Error Handler)에 연결(bridge)할 수 있게 해 줘요. 그러면 Camel consumer가 들어오는 메시지를 집어 올리는 동안 등에 발생한 예외가(가능한 경우) 메시지로 처리되어 라우팅 에러 핸들러에서 다뤄져요. 중요: 이건 서드파티 컴포넌트가 예외가 던져졌을 때 Camel에 알려 줄 수 있을 때만 가능해요. 일부 컴포넌트는 내부에서만 예외를 처리하기 때문에 bridgeErrorHandler를 쓸 수 없어요. 다른 상황에서는 이후 릴리스에서 서드파티 컴포넌트에 연결(hook)해서 이를 가능하게끔 Camel 컴포넌트를 개선할 수도 있어요. 기본으로 consumer는 org.apache.camel.spi.ExceptionHandler를 써서 예외를 다루고, 예외는 WARN 또는 ERROR 레벨로 로그가 남고 무시돼요.	false	boolean
lazyStartProducer (producer)	producer를 지연 시작(lazy, 첫 메시지 시점)할지 여부예요. 지연 시작을 쓰면 producer가 시작 중 실패해서 라우트 시작이 실패하는 상황에서도 CamelContext와 라우트가 시작될 수 있어요. 시작을 지연하면 시작 실패를 라우팅 중에 Camel의 라우팅 에러 핸들러로 처리할 수 있죠. 단, 첫 메시지가 처리될 때 producer를 만들고 시작하는 데 시간이 조금 걸려서 전체 처리 시간이 길어질 수 있다는 점은 유의하세요.	false	boolean
autowiredEnabled (advanced)	오토와이어링(autowiring)을 켤지 여부예요. 오토와이어링 대상 옵션(옵션이 autowired로 표시돼 있어야 함)을 레지스트리에서 찾아 일치하는 타입의 인스턴스가 하나뿐이면 그 인스턴스가 컴포넌트에 설정돼요. JDBC 데이터소스, JMS 커넥션 팩토리, AWS 클라이언트 등을 자동 구성할 때 쓸 수 있어요.	true	boolean
healthCheckConsumerEnabled (health)	이 컴포넌트의 consumer 기반 헬스 체크를 모두 켜거나 끌 때 사용해요.	true	boolean
healthCheckProducerEnabled (health)	이 컴포넌트의 producer 기반 헬스 체크를 모두 켜거나 끌 때 사용해요. 참고: Camel은 기본으로 producer 기반 헬스 체크를 모두 꺼 두었어요. `camel.health.producersEnabled=true`로 설정하면 producer 체크를 전역으로 켤 수 있어요.	true	boolean

엔드포인트 옵션 (Endpoint Options)

Azure Files 엔드포인트는 다음 URI 문법으로 설정해요:

azure-files:account/share

다음 path 및 query 파라미터를 지원해요:

Path 파라미터 (Path Parameters)

Name	Description	Type
account (common)	필수 사용할 계정이에요.	String
share (common)	필수 사용할 share예요.	String
port (common)	FTP 서버의 포트예요.	int
directoryName (common)	시작 디렉터리예요.	String

Query 파라미터 (Query Parameters)

Name	Description	Default	Type
credentialType (common)
채택할 자격 증명 전략을 결정해요.

Enum 값:

SHARED_ACCOUNT_KEY
SHARED_KEY_CREDENTIAL
AZURE_IDENTITY
AZURE_SAS

| SHARED_ACCOUNT_KEY | CredentialType | | disconnect (common) | 사용 직후 원격 FTP 서버에서 연결을 끊을지 여부예요. disconnect는 현재 FTP 서버 연결만 끊어요. 멈추고 싶은 consumer가 있다면 consumer/route를 멈추는 게 맞아요. | false | boolean | | doneFileName (common) | Producer: 이 값을 지정하면 원본 파일을 쓴 뒤 두 번째 done 파일을 써요. done 파일은 비어 있어요. 이 옵션은 done 파일 이름을 정하는 데 쓰는데, 고정 이름을 지정하거나 동적 플레이스홀더를 쓸 수 있어요. done 파일은 항상 원본 파일과 같은 폴더에 써져요. Consumer: 이 값을 지정하면 done 파일이 존재할 때만 파일을 소비해요. 이 옵션도 done 파일 이름을 정하는 데 쓰이고, 고정 이름이나 동적 플레이스홀더를 쓸 수 있어요. done 파일은 항상 원본 파일과 같은 폴더에 있다고 간주돼요. 동적 플레이스홀더는 $\{file.name}과 $\{file.name.next}만 지원돼요. | | String | | fileName (common) | File Language 같은 Expression을 써서 파일 이름을 동적으로 정해요. consumer에서는 파일 이름 필터로 쓰이고, producer에서는 쓸 파일 이름을 평가하는 데 쓰여요. 표현식이 설정되면 CamelFileName 헤더보다 우선해요. (참고: 헤더 자체도 Expression일 수 있어요.) 표현식 옵션은 String과 Expression 타입을 모두 지원해요. 표현식이 String 타입이면 항상 File Language로 평가되고, Expression 타입이면 지정한 Expression 타입이 쓰여서 예컨대 OGNL 표현식도 쓸 수 있어요. consumer에서는 파일 이름을 필터링하는 데 쓸 수 있어서, File Language 문법으로 mydata-$\{date:now:yyyyMMdd}.txt처럼 오늘의 파일을 소비할 수도 있어요. producer는 CamelOverruleFileName 헤더를 지원하는데, 이 헤더는 기존 CamelFileName 헤더보다 우선하고 한 번만 쓰여요. CamelFileName을 임시로 저장했다가 복구하는 수고를 덜어 주죠. | | String | | jailStartingDirectory (common) | 파일 쓰기를 시작 디렉터리(와 하위)로만 한정(jail)할 때 사용해요. 기본으로 켜져 있어서 Camel이 시작 디렉터리 밖에 파일을 쓰지 못하게 막아요(기본 상태에서 더 안전하도록). 이걸 끄면 부모 폴더나 루트 폴더 같은 시작 디렉터리 밖의 디렉터리에 파일을 쓸 수 있어요. localWorkDirectory를 쓰는 consumer에서는 다운로드된 파일도 설정된 localWorkDirectory 안에만 머물도록 제한해요. | true | boolean | | sharedKey (common) | 공유 키(스토리지 계정 키)예요. | | String | | delete (consumer) | true면 파일이 성공적으로 처리된 뒤 삭제돼요. | false | boolean | | moveFailed (consumer) | Simple 언어 기반으로 이동 실패 표현식을 설정해요. 예컨대 파일을 .error 하위 디렉터리로 옮기려면 .error를 쓰세요. 참고: 파일을 실패 위치로 옮길 때 Camel이 오류를 처리하고 그 파일을 다시 집어 오지 않아요. | | String | | noop (consumer) | true면 파일을 어떤 식으로도 옮기거나 삭제하지 않아요. 읽기 전용 데이터나 ETL 유형 요건에 적합한 옵션이에요. noop=true면 Camel이 같은 파일을 반복해서 소비하지 않도록 idempotent=true도 함께 설정해요. | false | boolean | | preMove (consumer) | 처리 전에 파일을 옮길 때 파일 이름을 동적으로 정하는 데 쓰는 표현식(File Language 등)이에요. 예컨대 진행 중인 파일을 order 디렉터리로 옮기려면 이 값을 order로 설정해요. | | String | | preSort (consumer) |

pre-sort가 켜지면 consumer가 폴링 중에 파일 시스템에서 가져온 파일·디렉터리 이름을 정렬해요. 파일을 정렬된 순서로 다뤄야 할 때 유용하죠. pre-sort는 consumer가 필터링을 시작해 Camel이 처리할 파일을 받아들이기 전에 실행돼요. 이 옵션은 기본값이 false라서 꺼져 있어요. 지원되는 값은 다음과 같아요: name(파일 이름 기준 정렬), modified(최종 수정 타임스탬프 기준 정렬), size(파일 크기 기준 정렬). 내림차순(역순)으로 정렬하려면 값 앞에 마이너스 기호를 붙이세요(예: -modified는 최신 파일부터 정렬). 값 true는 name의 별칭이에요(하위 호환).

Enum 값:

true
false
name
-name
modified
-modified
size
-size

| | String | | recursive (consumer) | 디렉터리라면 모든 하위 디렉터리에서도 파일을 찾아요. | false | boolean | | resumeDownload (consumer) | 이어받기(resume download)를 켤지 설정해요. 이어받기를 지원하려면 다운로드한 파일을 로컬 디렉터리에 저장해야 하므로 localWorkDirectory 옵션도 함께 설정해야 해요. | false | boolean | | sendEmptyMessageWhenIdle (consumer) | 폴링 consumer가 아무 파일도 가져오지 못했을 때 이 옵션을 켜면 빈 메시지(바디 없음)를 대신 보내요. | false | boolean | | streamDownload (consumer) | 로컬 작업 디렉터리를 쓰지 않을 때의 다운로드 방식을 정해요. true면 원격 파일을 읽는 대로 라우트로 스트리밍하고, false면 원격 파일을 라우트로 보내기 전에 메모리에 올려요. 이 옵션을 켜면 stepwise=false로 설정해야 해요. 둘은 동시에 켤 수 없거든요. | false | boolean | | bridgeErrorHandler (consumer (advanced)) | consumer를 Camel 라우팅 에러 핸들러(routing Error Handler)에 연결(bridge)할 수 있게 해 줘요. 그러면 Camel consumer가 들어오는 메시지를 집어 올리는 동안 등에 발생한 예외가(가능한 경우) 메시지로 처리되어 라우팅 에러 핸들러에서 다뤄져요. 중요: 이건 서드파티 컴포넌트가 예외가 던져졌을 때 Camel에 알려 줄 수 있을 때만 가능해요. 일부 컴포넌트는 내부에서만 예외를 처리하기 때문에 bridgeErrorHandler를 쓸 수 없어요. 다른 상황에서는 이후 릴리스에서 서드파티 컴포넌트에 연결(hook)해서 이를 가능하게끔 Camel 컴포넌트를 개선할 수도 있어요. 기본으로 consumer는 org.apache.camel.spi.ExceptionHandler를 써서 예외를 다루고, 예외는 WARN 또는 ERROR 레벨로 로그가 남고 무시돼요. | false | boolean | | download (consumer (advanced)) | FTP consumer가 파일을 다운로드할지 여부예요. false로 설정하면 메시지 바디는 null이지만 consumer는 여전히 파일 이름, 파일 크기 등 파일에 관한 정보를 담은 Camel Exchange를 발생시켜요. 다만 파일 자체는 다운로드되지 않아요. | false | boolean | | exceptionHandler (consumer (advanced)) | consumer가 커스텀 ExceptionHandler를 쓰게 할 때 사용해요. bridgeErrorHandler 옵션이 켜져 있으면 이 옵션은 쓰이지 않는다는 점에 유의하세요. 기본으로 consumer는 예외를 직접 다루고, 예외는 WARN 또는 ERROR 레벨로 로그가 남고 무시돼요. | | ExceptionHandler | | exchangePattern (consumer (advanced)) |

consumer가 exchange를 만들 때의 exchange 패턴을 설정해요.

Enum 값:

InOnly
InOut

| | ExchangePattern | | inProgressRepository (consumer (advanced)) | 플러그형 in-progress 저장소(org.apache.camel.spi.IdempotentRepository)예요. in-progress 저장소는 현재 소비 중인 파일을 기록하는 데 쓰여요. 기본으로 메모리 기반 저장소를 써요. | | IdempotentRepository | | localWorkDirectory (consumer (advanced)) | 소비할 때 로컬 작업 디렉터리를 쓰면 원격 파일 내용을 로컬 파일에 바로 저장해서 메모리에 올리는 걸 피할 수 있어요. 아주 큰 원격 파일을 소비할 때 메모리를 아낄 수 있어서 유익해요. | | String | | onCompletionExceptionHandler (consumer (advanced)) | consumer가 commit 또는 rollback을 수행하는 파일 on-completion 과정에서 발생한 예외를 다루는 커스텀 org.apache.camel.spi.ExceptionHandler를 쓸 때 사용해요. 기본 구현은 예외를 WARN 레벨로 로그에 남기고 무시해요. | | ExceptionHandler | | pollStrategy (consumer (advanced)) | 플러그형 org.apache.camel.PollingConsumerPollingStrategy로, Exchange가 만들어지고 Camel에서 라우팅되기 전에 폴링 작업 중에 보통 일어나는 오류 처리를 직접 제어할 수 있는 커스텀 구현을 제공할 때 사용해요. | | PollingConsumerPollStrategy | | processStrategy (consumer (advanced)) | 플러그형 org.apache.camel.component.file.GenericFileProcessStrategy로, 자체 readLock 옵션 같은 것을 구현할 때 쓸 수 있어요. 특별한 ready 파일이 존재하는 것처럼 파일을 소비하기 전에 특수 조건을 만족해야 하는 경우에도 쓸 수 있어요. 이 옵션을 설정하면 readLock 옵션은 적용되지 않아요. | | GenericFileProcessStrategy | | throwExceptionOnConnectFailed (consumer (advanced)) | 연결에 실패했을 때(시도를 다 썼을 때) 예외를 던질지 여부예요. 기본으로는 예외를 던지지 않고 WARN을 로그에 남겨요. 이 옵션을 쓰면 예외를 던지도록 만들고, org.apache.camel.spi.PollingConsumerPollStrategy rollback 메서드에서 던져진 예외를 처리할 수 있어요. | false | boolean | | checksumFileAlgorithm (producer) |

이 값을 지정하면 Camel이 쓴 파일로부터 체크섬을 계산해서 결과를 CamelFileChecksum 헤더에 저장해요.

Enum 값:

MD2
MD5
SHA_1
SHA_224
SHA_256
SHA_384
SHA_512
SHA_512_224
SHA_512_256
SHA3_224
SHA3_256
SHA3_384
SHA3_512

같은 이름의 파일이 이미 존재할 때 어떻게 할지 정해요. 기본값인 Override는 기존 파일을 대체해요. - Append - 기존 파일에 내용을 더해요. - Fail - 이미 파일이 존재한다는 뜻의 GenericFileOperationException을 던져요. - Ignore - 문제를 조용히 무시하고 기존 파일을 대체하지 않지만 모든 게 잘 됐다고 가정해요. - Move - moveExisting 옵션도 함께 설정해야 하는 옵션이에요. eagerDeleteTargetFile 옵션으로 파일을 옮길 때 기존 파일이 이미 있을 경우의 동작을 제어할 수 있고, 그렇지 않으면 이동 작업이 실패해요. Move 옵션은 대상 파일을 쓰기 전에 기존 파일을 옮겨요. - TryRename은 tempFileName 옵션을 쓸 때만 적용돼요. 존재 여부 검사 없이 임시 이름에서 실제 이름으로 파일 이름 바꾸기를 시도하게 해 줘요. 이 검사는 일부 파일 시스템, 특히 FTP 서버에서 더 빠를 수 있어요.

Enum 값:

Override
Append
Fail
Ignore
Move
TryRename

| Override | GenericFileExist | | flatten (producer) | flatten은 파일 이름 경로를 평평하게 만들어 선행 경로를 떼고 파일 이름만 남겨요. 이러면 하위 디렉터리까지 재귀적으로 소비하면서도, 예컨대 다른 디렉터리에 파일을 쓸 때는 하나의 디렉터리에 쓰이게 할 수 있어요. producer에서 true로 설정하면 CamelFileName 헤더의 어떤 파일 이름에서든 선행 경로가 반드시 떼어져요. | false | boolean | | tempFileName (producer) | tempPrefix 옵션과 같지만 File Language를 쓰기 때문에 임시 파일 이름을 더 세밀하게 제어할 수 있어요. tempFilename의 위치는 base uri의 대상 디렉터리가 아니라 'fileName' 옵션에 있는 최종 파일 위치를 기준으로 해요. 예컨대 fileName 옵션에 디렉터리 접두어 dir/finalFilename이 들어 있다면 tempFileName은 그 하위 디렉터리 dir를 기준으로 해요. | | String | | tempPrefix (producer) | 임시 이름으로 파일을 쓰고, 쓰기가 끝나면 실제 이름으로 바꿀 때 사용하는 옵션이에요. 쓰고 있는 파일을 식별하는 데 쓸 수 있고, 배타 읽기 잠금을 쓰지 않는 consumer가 진행 중인 파일을 읽는 걸 막아 줘요. FTP에서 큰 파일을 업로드할 때 자주 쓰여요. | | String | | allowNullBody (producer (advanced)) | 파일 쓰기 중에 null 바디를 허용할지 지정해요. true면 빈 파일이 만들어지고, false인 상태에서 null 바디를 파일 컴포넌트로 보내려 하면 'Cannot write null body to file.'이라는 GenericFileWriteException이 던져져요. fileExist 옵션이 'Override'면 파일이 잘리고(truncate), append로 설정돼 있으면 파일은 그대로 유지돼요. | false | boolean | | disconnectOnBatchComplete (producer (advanced)) | 배치 업로드가 끝나자마자 원격 FTP 서버에서 연결을 끊을지 여부예요. disconnectOnBatchComplete는 현재 FTP 서버 연결만 끊어요. | false | boolean | | eagerDeleteTargetFile (producer (advanced)) | 기존 대상 파일을 즉시(eagerly) 삭제할지 여부예요. 이 옵션은 fileExists=Override와 tempFileName 옵션을 함께 쓸 때만 적용돼요. 임시 파일을 쓰기 전에 대상 파일을 삭제하는 동작을 끄려면(false로 설정) 이 옵션을 쓰세요. 예컨대 큰 파일을 쓰면서 임시 파일이 쓰이는 동안 대상 파일이 존재하게 유지하고 싶을 수 있죠. 그러면 대상 파일은 임시 파일이 대상 파일 이름으로 바뀌기 직전, 막판에만 삭제돼요. 이 옵션은 fileExist=Move가 켜져 있고 기존 파일이 있을 때 기존 파일을 삭제할지 제어하는 데도 쓰여요. 이 옵션(copyAndDeleteOnRenameFails)이 false면 기존 파일이 있을 때 예외가 던져지고, true면 이동 작업 전에 기존 파일이 삭제돼요. | true | boolean | | keepLastModified (producer (advanced)) | 소스 파일의 최종 수정 타임스탬프를(있다면) 유지해요. 타임스탬프를 찾을 때 FileConstants.FILE_LAST_MODIFIED 헤더를 써요. 이 헤더에는 java.util.Date 또는 타임스탬프를 담은 long이 들어갈 수 있어요. 타임스탬프가 있고 옵션이 켜져 있으면 쓰여진 파일에 그 타임스탬프가 설정돼요. 참고: 이 옵션은 파일 producer에만 적용돼요. ftp producer들과는 함께 쓸 수 없어요. | false | boolean | | lazyStartProducer (producer (advanced)) | producer를 지연 시작(lazy, 첫 메시지 시점)할지 여부예요. 지연 시작을 쓰면 producer가 시작 중 실패해서 라우트 시작이 실패하는 상황에서도 CamelContext와 라우트가 시작될 수 있어요. 시작을 지연하면 시작 실패를 라우팅 중에 Camel의 라우팅 에러 핸들러로 처리할 수 있죠. 단, 첫 메시지가 처리될 때 producer를 만들고 시작하는 데 시간이 조금 걸려서 전체 처리 시간이 길어질 수 있다는 점은 유의하세요. | false | boolean | | moveExistingFileStrategy (producer (advanced)) | fileExist=Move가 설정됐을 때 특수한 이름 지정 토큰으로 파일을 옮기는 데 쓰는 전략(커스텀 전략)이에요. 커스텀 전략을 제공하지 않으면 기본 구현이 쓰여요. | | FileMoveExistingStrategy | | autoCreate (advanced) | 파일 경로에 없는 디렉터리를 자동으로 만들어요. 파일 consumer라는 건 시작 디렉터리를 만드는 걸 뜻하고, 파일 producer라는 건 파일을 쓸 디렉터리를 만드는 걸 뜻해요. | true | boolean | | browseLimit (advanced) | 브라우징용으로 메모리에 유지할 최대 메시지 수예요. 무제한으로 하려면 0을 쓰세요. | 100 | int | | connectTimeout (advanced) | 연결이 성립되기를 기다리는 연결 타임아웃을 설정해요. FTPClient와 JSCH 둘 다 써요. | 10000 | int | | maximumReconnectAttempts (advanced) | 원격 FTP 서버에 연결하려 할 때 Camel이 수행할 최대 재연결 시도 횟수를 지정해요. 이 동작을 끄려면 0을 쓰세요. | | int | | reconnectDelay (advanced) | 재연결 시도 전에 Camel이 기다리는 지연 시간(밀리초)이에요. | 1000 | long | | timeout (advanced) | 응답을 기다리는 데이터 타임아웃을 설정해요. FTPClient만 써요. | 30000 | int | | antExclude (filter) | Ant 스타일 필터 제외(exclusion)예요. antInclude와 antExclude를 둘 다 쓰면 antExclude가 antInclude보다 우선해요. 여러 개의 제외 항목은 콤마로 구분해서 지정할 수 있어요. | | String | | antFilterCaseSensitive (filter) | ant 필터에 대소문자 구분 플래그를 설정해요. | true | boolean | | antInclude (filter) | Ant 스타일 필터 포함(inclusion)이에요. 여러 개의 포함 항목은 콤마로 구분해서 지정할 수 있어요. | | String | | eagerMaxMessagesPerPoll (filter) | maxMessagesPerPoll의 제한이 즉시(eager) 적용될지 제어해요. eager면 파일을 스캔하는 동안 제한이 걸리고, false면 모든 파일을 스캔한 다음 정렬을 수행해요. 이 옵션을 false로 하면 모든 파일을 먼저 정렬한 다음 폴링을 제한할 수 있어요. 다만 정렬을 위해 모든 파일 정보가 메모리에 올라가야 해서 메모리 사용량이 더 커진다는 점은 유의하세요. | true | boolean | | exclude (filter) | 파일 이름이 정규식 패턴과 일치하면(대소문자 무시) 파일을 제외할 때 사용해요. 참고: 플러스 기호 같은 특수 기호를 쓴다면 엔드포인트 URI로 설정할 때 RAW() 문법으로 설정해야 해요. 자세한 내용은 configuring endpoint uris를 보세요. | | String | | excludeExt (filter) | 파일 확장자 이름이 일치하면(대소문자 무시) 파일을 제외할 때 사용해요. 예컨대 bak 파일을 제외하려면 excludeExt=bak을 쓰세요. 여러 확장자는 콤마로 구분할 수 있어서, bak과 dat 파일을 모두 제외하려면 excludeExt=bak,dat처럼 쓰면 돼요. 파일 확장자는 모든 부분을 포함한다는 점에 유의하세요. 예컨대 mydata.tar.gz라는 파일의 확장자는 tar.gz이에요. 더 유연하게 쓰려면 include/exclude 옵션을 쓰세요. | | String | | filter (filter) | org.apache.camel.component.file.GenericFileFilter 클래스로 주입할 수 있는 플러그형 필터예요. accept() 메서드가 false를 반환하면 파일을 건너뛰어요. | | GenericFileFilter | | filterDirectory (filter) | Simple 언어 기반으로 디렉터리를 필터링해요. 예컨대 현재 날짜로 필터링하려면 $\{date:now:yyyMMdd} 같은 심플한 날짜 패턴을 쓸 수 있어요. | | String | | filterFile (filter) | Simple 언어 기반으로 파일을 필터링해요. 예컨대 파일 크기로 필터링하려면 $\{file:size} 5000을 쓸 수 있어요. | | String | | idempotent (filter) | Idempotent Consumer EIP 패턴을 써서 Camel이 이미 처리한 파일을 건너뛰게 하는 옵션이에요. 기본으로 1000개 항목을 담는 메모리 기반 LRUCache를 써요. noop=true면 같은 파일을 반복해서 소비하지 않도록 idempotent도 함께 켜져요. | false | Boolean | | idempotentEager (filter) | 파일 이름을 idempotent 저장소에 즉시(eagerly) 추가할지, exchange가 끝날 때까지 기다릴지 설정해요. | true | Boolean | | idempotentKey (filter) | 커스텀 idempotent 키를 쓸 때 사용해요. 기본은 파일의 절대 경로예요. File Language를 쓸 수 있어서, 예컨대 파일 이름과 파일 크기를 쓰려면 idempotentKey=$\{file:name}-$\{file:size}처럼 하면 돼요. | | String | | idempotentRepository (filter) | 플러그형 저장소(org.apache.camel.spi.IdempotentRepository)예요. 지정하지 않고 idempotent가 true면 기본으로 MemoryIdempotentRepository를 써요. | | IdempotentRepository | | include (filter) | 파일 이름이 정규식 패턴과 일치하면(대소문자 무시) 파일을 포함할 때 사용해요. 참고: 플러스 기호 같은 특수 기호를 쓴다면 엔드포인트 URI로 설정할 때 RAW() 문법으로 설정해야 해요. 자세한 내용은 configuring endpoint uris를 보세요. | | String | | includeExt (filter) | 파일 확장자 이름이 일치하면(대소문자 무시) 파일을 포함할 때 사용해요. 예컨대 txt 파일을 포함하려면 includeExt=txt를 쓰세요. 여러 확장자는 콤마로 구분할 수 있어서, txt와 xml 파일을 모두 포함하려면 includeExt=txt,xml처럼 쓰면 돼요. 파일 확장자는 모든 부분을 포함한다는 점에 유의하세요. 예컨대 mydata.tar.gz라는 파일의 확장자는 tar.gz이에요. 더 유연하게 쓰려면 include/exclude 옵션을 쓰세요. | | String | | maxDepth (filter) | 디렉터리를 재귀적으로 처리할 때 탐색할 최대 깊이예요. | 2147483647 | int | | maxMessagesPerPoll (filter) | 폴링당 모아 올 최대 메시지 수를 정해요. 기본으로는 최댓값이 없어요. 예컨대 서버를 시작할 때 수천 개의 파일이 있지 않도록 1000 같은 제한을 거는 데 쓸 수 있어요. 끄려면 0이나 음수를 넣으세요. 참고: 이 옵션을 쓰면 File과 FTP 컴포넌트가 정렬 전에 제한을 걸어요. 예컨대 파일이 100000개 있는데 maxMessagesPerPoll=500을 쓰면 처음 500개의 파일만 집어 올려진 다음 정렬돼요. 모든 파일을 먼저 스캔한 다음 정렬하려면 eagerMaxMessagesPerPoll 옵션을 false로 설정하세요. | | int | | minDepth (filter) | 디렉터리를 재귀적으로 처리할 때 처리를 시작할 최소 깊이예요. minDepth=1이면 기본 디렉터리, minDepth=2이면 첫 하위 디렉터리를 뜻해요. | | int | | move (filter) | 처리 후에 파일을 옮길 때 파일 이름을 동적으로 정하는 데 쓰는 표현식(Simple Language 등)이에요. 파일을 .done 하위 디렉터리로 옮기려면 그냥 .done을 입력하면 돼요. | | String | | exclusiveReadLockStrategy (lock) | org.apache.camel.component.file.GenericFileExclusiveReadLockStrategy 구현으로 주입할 수 있는 플러그형 읽기 잠금(read-lock)이에요. | | GenericFileExclusiveReadLockStrategy | | readLock (lock) |

consumer가 파일에 배타 읽기 잠금(exclusive read-lock)이 있을 때만(즉, 파일이 진행 중이거나 쓰이고 있지 않을 때) 폴링하도록 하는 데 쓰여요. Camel은 파일 잠금이 허용될 때까지 기다려요. 이 옵션이 제공하는 내장 전략은 다음과 같아요: - none - 읽기 잠금을 쓰지 않아요 - markerFile - Camel이 마커 파일(fileName.camelLock)을 만들고 그 파일에 잠금을 걸어요. 이 옵션은 FTP 컴포넌트에서는 쓸 수 없어요 - changed - 변경 감지(changed)는 파일 길이/수정 타임스탬프로 파일이 현재 복사 중인지 판단해요. 판단에 최소 1초를 쓰기 때문에 다른 옵션만큼 빠르게 파일을 소비할 수는 없지만, JDK IO API로는 파일이 다른 프로세스에 쓰이고 있는지 항상 알 수 있는 게 아니라서 더 신뢰할 수 있을 수 있어요. 검사 빈도를 정하려면 readLockCheckInterval 옵션을 쓸 수 있어요. - fileLock - java.nio.channels.FileLock을 쓰는 방식이에요. Windows OS와 FTP 컴포넌트에서는 쓸 수 없어요. 마운트/공유를 통해 원격 파일 시스템에 접근할 때는 그 파일 시스템이 분산 파일 잠금을 지원하지 않는 한 이 방식은 피해야 해요. - rename - 배타 읽기 잠금을 얻을 수 있는지 시험해 보려고 파일 이름 바꾸기를 시도하는 방식이에요. - idempotent - (file 컴포넌트 전용) idempotent는 idempotentRepository를 읽기 잠금으로 쓰는 방식이에요. idempotent 저장소 구현이 지원한다면 클러스터링을 지원하는 읽기 잠금을 쓸 수 있어요. - idempotent-changed - (file 컴포넌트 전용) idempotent-changed는 idempotentRepository와 changed를 결합한 읽기 잠금이에요. idempotent 저장소 구현이 지원한다면 클러스터링을 지원하는 읽기 잠금을 쓸 수 있어요. - idempotent-rename - (file 컴포넌트 전용) idempotent-rename은 idempotentRepository와 rename을 결합한 읽기 잠금이에요. idempotent 저장소 구현이 지원한다면 클러스터링을 지원하는 읽기 잠금을 쓸 수 있어요. 참고: 여러 읽기 잠금이 모두 클러스터 모드에 적합한 건 아니에요. 서로 다른 노드의 동시 consumer가 공유 파일 시스템에서 같은 파일을 두고 경쟁하는 상황에서는 특히 그래요. markerFile은 거의 원자적인 동작으로 빈 마커 파일을 만들지만 클러스터에서 동작한다는 보장은 없어요. fileLock이 더 잘 동작할 수 있지만 그러려면 파일 시스템이 분산 파일 잠금을 지원해야 하고요. idempotent 읽기 잠금은 idempotent 저장소가 클러스터링을 지원하면 클러스터링을 지원할 수 있어요. 예컨대 Hazelcast Component나 Infinispan 같은 경우죠.

Enum 값:

none
markerFile
fileLock
rename
changed
idempotent
idempotent-changed
idempotent-rename

| none | String | | readLockCheckInterval (lock) | 읽기 잠금이 지원한다면 읽기 잠금의 검사 간격(밀리초)이에요. 이 간격은 읽기 잠금을 얻으려는 시도 사이에 잠을 자는 데 쓰여요. 예컨대 changed 읽기 잠금을 쓸 때는 느린 쓰기를 고려해 더 긴 간격을 설정할 수 있어요. 기본값인 1초는 producer가 파일을 아주 느리게 쓸 때 너무 빠를 수 있어요. 참고: FTP에서는 기본 readLockCheckInterval이 5000이에요. readLockTimeout 값은 readLockCheckInterval보다 커야 하고, 경험적으로는 readLockCheckInterval의 최소 2배 이상으로 잡는 게 좋아요. 타임아웃에 걸리기 전에 읽기 잠금 프로세스가 잠금을 잡아 보려고 충분한 시간을 갖도록 하기 위해서예요. | 1000 | long | | readLockDeleteOrphanLockFiles (lock) | Camel이 제대로 멈추지 못했을 때(예: JVM 크래시) 파일 시스템에 남을 수 있는 고아(orphan) 읽기 잠금 파일을, 마커 파일 기반 읽기 잠금이 시작 시 삭제할지 여부예요. 이 옵션을 false로 바꾸면 어떤 고아 잠금 파일이 있든 Camel이 그 파일을 집어 올리려 하지 않아요. 다른 노드가 같은 공유 디렉터리에서 파일을 동시에 읽고 있는 경우일 수도 있고요. | true | boolean | | readLockLoggingLevel (lock) |

읽기 잠금을 얻지 못했을 때 쓰이는 로깅 레벨이에요. 기본으로 DEBUG가 기록돼요. 이 레벨을 바꿀 수 있어서, 예컨대 OFF로 하면 로그가 전혀 남지 않아요. 이 옵션은 readLock이 changed, fileLock, idempotent, idempotent-changed, idempotent-rename, rename 타입일 때만 적용돼요.

Enum 값:

TRACE
DEBUG
INFO
WARN
ERROR
OFF

| DEBUG | LoggingLevel | | readLockMarkerFile (lock) | changed, rename 또는 배타 읽기 잠금 타입에서 마커 파일을 쓸지 여부예요. 기본으로 마커 파일도 함께 써서 다른 프로세스가 같은 파일을 집어 올리는 걸 막아요. 이 동작은 이 옵션을 false로 설정하면 끌 수 있어요. 예컨대 Camel 애플리케이션이 파일 시스템에 마커 파일을 쓰는 걸 원하지 않을 때죠. | true | boolean | | readLockMinAge (lock) | 이 옵션은 readLock=changed일 때만 적용돼요. 읽기 잠금을 얻으려 시도하기 전에 파일이 최소한의 나이(minimum age)를 갖도록 지정할 수 있어요. 예컨대 readLockMinAge=300s를 쓰면 파일이 최소 5분은 됐어야 해요. 그 나이 이상인 파일에만 잠금을 시도하니 changed 읽기 잠금을 더 빠르게 할 수 있어요. | 0 | long | | readLockMinLength (lock) | 이 옵션은 readLock=changed일 때만 적용돼요. 최소 파일 길이를 설정할 수 있어요. 기본으로 Camel은 파일에 데이터가 있다고 기대하기 때문에 기본값은 1이에요. 이 옵션을 0으로 하면 길이 0인 파일도 소비할 수 있어요. | 1 | long | | readLockRemoveOnCommit (lock) | 이 옵션은 readLock=idempotent일 때만 적용돼요. 파일 처리가 성공해서 commit이 일어났을 때 idempotent 저장소에서 파일 이름 항목을 제거할지 지정해요. 기본으로는 제거하지 않는데, 그래야 경쟁 상태(race-condition)가 생기지 않아서 다른 활성 노드가 그 파일을 잡으려 시도하지 않아요. 대신 idempotent 저장소가 제거(eviction) 전략을 지원한다면 X분 후에 파일 이름 항목을 제거하도록 설정할 수 있어요. 이러면 경쟁 상태 문제가 없어요. 자세한 내용은 readLockIdempotentReleaseDelay 옵션을 보세요. | false | boolean | | readLockRemoveOnRollback (lock) | 이 옵션은 readLock=idempotent일 때만 적용돼요. 파일 처리가 실패해서 rollback이 일어났을 때 idempotent 저장소에서 파일 이름 항목을 제거할지 지정해요. 이 옵션이 false면 파일 이름 항목이 확정(commit한 것처럼)돼요. | true | boolean | | readLockTimeout (lock) | 읽기 잠금이 지원한다면 읽기 잠금의 선택적 타임아웃(밀리초)이에요. 읽기 잠금이 허용되지 않은 채 타임아웃이 발생하면 Camel은 그 파일을 건너뛰어요. 다음 폴링 때 Camel은 그 파일을 다시 시도하고, 이번에는 읽기 잠금이 허용될지도 몰라요. 영원히 기다리려면 0 이하의 값을 쓰세요. 현재 fileLock, changed, rename이 타임아웃을 지원해요. 참고: FTP에서는 기본 readLockTimeout 값이 10000이 아니라 20000이에요. readLockTimeout 값은 readLockCheckInterval보다 커야 하고, 경험적으로는 readLockCheckInterval의 최소 2배 이상으로 잡는 게 좋아요. 타임아웃에 걸리기 전에 읽기 잠금 프로세스가 잠금을 잡아 보려고 충분한 시간을 갖도록 하기 위해서예요. | 10000 | long | | backoffErrorThreshold (scheduler) | backoffMultipler가 동작하기 전에 연속으로 일어나야 하는 에러 폴링(오류로 실패한 폴링) 횟수예요. | | int | | backoffIdleThreshold (scheduler) | backoffMultipler가 동작하기 전에 연속으로 일어나야 하는 유휴(idle) 폴링 횟수예요. | | int | | backoffMultiplier (scheduler) | 유휴/에러 폴링이 연속으로 여러 번 일어나면 예약 폴링 consumer가 백오프(backoff)하도록 해 줘요. multiplier는 다음 실제 시도가 일어나기 전에 건너뛸 폴링 횟수예요. 이 옵션을 쓸 때는 backoffIdleThreshold와/또는 backoffErrorThreshold도 함께 설정해야 해요. | | int | | delay (scheduler) | 다음 폴링 전까지의 밀리초예요. | 500 | long | | greedy (scheduler) | greedy가 켜지면 이전 실행이 메시지를 1개 이상 폴링했을 때 ScheduledPollConsumer가 즉시 다시 실행돼요. | false | boolean | | initialDelay (scheduler) | 첫 폴링이 시작되기 전까지의 밀리초예요. | 1000 | long | | repeatCount (scheduler) | 발동(fire) 횟수의 최대 한도를 지정해요. 1로 설정하면 스케줄러가 한 번만 발동하고, 5로 설정하면 다섯 번만 발동해요. 0이나 음수는 영원히 발동한다는 뜻이에요. | 0 | long | | runLoggingLevel (scheduler) |

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

Enum 값:

TRACE
DEBUG
INFO
WARN
ERROR
OFF

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

Enum 값:

NANOSECONDS
MICROSECONDS
MILLISECONDS
SECONDS
MINUTES
HOURS
DAYS

메시지 헤더 (Message Headers)

Azure Files 컴포넌트가 지원하는 메시지 헤더(들)는 아래와 같아요:

Name	Description	Type
CamelFileLength (consumer) Constant: `FILE_LENGTH`	파일 크기를 담은 long 값이에요.	long
CamelFileLastModified (consumer) Constant: `FILE_LAST_MODIFIED`	파일의 최종 수정 타임스탬프를 담은 Long 값이에요.	long
CamelFileNameOnly (consumer) Constant: `FILE_NAME_ONLY`	파일 이름만 있어요(선행 경로가 없는 이름).	String
CamelFileName (common) Constant: `FILE_NAME`	(producer) 쓸 파일의 이름을 지정해요(엔드포인트 디렉터리 기준 상대 경로). 이 이름은 String, file 또는 simple 언어 표현식이 들어간 String, 또는 Expression 객체일 수 있어요. null이면 Camel이 메시지의 고유 ID 기반으로 파일 이름을 자동 생성해요. (consumer) 엔드포인트에 설정된 시작 디렉터리에서 오프셋을 둔 상대 파일 경로로 표현한 소비된 파일의 이름이에요.	String
CamelFileNameConsumed (consumer) Constant: `FILE_NAME_CONSUMED`	소비된 파일의 이름이에요.	String
CamelFileAbsolute (consumer) Constant: `FILE_ABSOLUTE`	소비된 파일이 절대 경로인지 아닌지를 지정하는 boolean 옵션이에요. 상대 경로라면 보통 false여야 해요. 절대 경로는 보통 쓰지 않지만 move 옵션에 추가해서 파일을 절대 경로로 옮길 수 있게 했어요. 다른 곳에서도 쓸 수 있고요.	Boolean
CamelFileAbsolutePath (consumer) Constant: `FILE_ABSOLUTE_PATH`	파일의 절대 경로예요. 상대 파일이라면 이 경로 대신 상대 경로가 들어가요.	String
CamelFilePath (consumer) Constant: `FILE_PATH`	파일 경로예요. 상대 파일이면 시작 디렉터리, 절대 파일이면 절대 경로예요.	String
CamelFileRelativePath (consumer) Constant: `FILE_RELATIVE_PATH`	상대 경로예요.	String
CamelFileParent (common) Constant: `FILE_PARENT`	부모 경로예요.	String
CamelFileNameProduced (producer) Constant: `FILE_NAME_PRODUCED`	쓰여진 출력 파일의 실제 절대 파일 경로(path name)예요. 이 헤더는 Camel이 설정하며, 쓰여진 파일의 이름을 최종 사용자에게 알려 주는 게 목적이에요.	String
CamelOverruleFileName (producer) Constant: `OVERRULE_FILE_NAME`	CamelFileName 헤더를 덮어쓰고 그 값을 대신 쓸 때 사용해요(단 한 번만, producer가 파일을 쓴 뒤 이 헤더를 제거하기 때문이에요). 값은 String만 가능해요. fileName 옵션이 설정돼 있어도 이 헤더는 여전히 평가된다는 점에 유의하세요.	Object
CamelRemoteFileInputStream (common) Constant: `REMOTE_FILE_INPUT_STREAM`	원격 파일 입력 스트림이에요.	InputStream
CamelFileLocalWorkPath (common) Constant: `FILE_LOCAL_WORK_PATH`	로컬 작업 디렉터리를 쓴다면 로컬 작업 파일의 경로예요.	String
CamelFileHost (common) Constant: `FILE_HOST`	원격 호스트 이름이에요.	String

엔드포인트 URI 예시 (Endpoint URI Examples)

azure-files://camelazurefiles.file.core.windows.net/samples?sv=2022-11-02&ss=f&srt=sco&sp=rwdlc&se=2023-06-18T22:29:13Z&st=2023-06-05T14:29:13Z&spr=https&sig=MPsMh8zci0v3To7IT9SKdaFGZV8ezno63m9C8s9bdVQ%3D

azure-files://camelazurefiles/samples/inbox/spam?sharedKey=FAKE502UyuBD...3Z%2BASt9dCmJg%3D%3D&delete=true

사용법 (Usage)

경로 (Paths)

경로 구분자는 /예요. 절대 경로는 경로 구분자로 시작해요. 절대 경로에는 share 이름이 포함되지 않고, 엔드포인트 시작 디렉터리가 아니라 share 루트를 기준으로 해요.

참고 (NOTE): 쓰이는 라이브러리의 로그 같은 일부 곳에서는 OS별 경로 구분자가 나타나고, 상대 경로는(현재 작업 디렉터리나 엔드포인트 시작 디렉터리가 아니라) share 루트를 기준으로 해요. 그래서 그런 부분은 대충 참고만 하세요.

동시성 (Concurrency)

이 컴포넌트는 엔드포인트에서 동시성(concurrency)을 지원하지 않아요.

더 알아보기 (More Information)

이 컴포넌트는 FTP 컴포넌트를 본떠 만들었어요. 그래서 더 많은 샘플과 세부 내용은 FTP 컴포넌트 페이지에 있어요.

이 컴포넌트는 실제 작업에 Azure Java SDK 라이브러리를 사용해요.

파일 소비하기 (Consuming Files)

원격 consumer는 기본으로 소비한 파일을 원격 클라우드 파일 서버에 그대로 둬요. 파일을 삭제하거나 다른 위치로 옮기고 싶다면 명시적으로 설정해야 해요. 예컨대 delete=true를 써서 파일을 삭제하거나, move=.done을 써서 .done 하위 디렉터리로 옮길 수 있어요.

Camel에서는 .-으로 시작하는 폴더는 재귀 폴링에서 제외돼요.

일반 File consumer와는 다른데, 일반 File consumer는 기본으로 파일을 .camel 하위 디렉터리로 옮겨요. 원격 consumer에 대해 Camel이 이 동작을 기본으로 하지 않는 이유는, 파일을 옮기거나 삭제할 권한이 기본으로 없을 수 있기 때문이에요.

바디 타입 옵션 (Body Type Options)

일치하는 파일마다 consumer는 선택된 바디 타입의 메시지를 Camel exchange로 보내요:

기본은 byte[]
streamDownload=true가 설정되면 java.io.InputStream
localWorkDirectory가 설정되면 java.io.File

바디 타입 설정은 가용 리소스, 성능 목표, 라우트 프로세서, 캐싱, 이어받기 등에 맞게 조정해야 해요.

제한 사항 (Limitations)

readLock 옵션을 쓰면 Camel이 쓰기 진행 중인 파일을 소비하지 않도록 강제할 수 있어요. 다만 이 옵션은 기본으로 꺼져 있는데, 사용자에게 쓰기 권한이 있어야 하기 때문이에요. 읽기 잠금에 대한 자세한 내용은 엔드포인트 옵션 표를 보세요.
파일이 쓰이는 중에 소비되는 걸 피하는 다른 방법도 있어요. 예컨대 임시 대상에 쓴 다음 쓰기가 끝난 뒤 파일을 옮기면 되죠.

readLock=changed는 최종 수정 시각에만 의존하고, 게다가 5초보다 촘촘한 정밀도는 문제가 될 수 있어요.

move나 preMove 옵션으로 파일을 옮길 때 파일은 share 안으로 한정돼요. consumer가 엔드포인트 share 밖으로 파일을 옮기는 걸 막아 주죠.

Exchange 프로퍼티 (Exchange Properties)

consumer는 다음 exchange 프로퍼티를 설정해요

Header	Description
`CamelBatchIndex`	이 배치에서 소비 중인 전체 파일 수 중 현재 인덱스예요.
`CamelBatchSize`	이 배치에서 소비 중인 파일의 총 개수예요.
`CamelBatchComplete`	이 배치에 더 이상 파일이 없으면 true예요.

파일 생산하기 (Producing Files)

Files producer는 두 바디 타입에 맞춰 최적화돼 있어요:

CamelFileLength 헤더가 설정돼 있으면 java.io.InputStream
byte[]

어느 쪽이든 원격 파일 크기를 먼저 할당한 다음 바디 내용으로 다시 써요. 선언된 파일 길이와 스트림 길이가 일치하지 않으면 원격 파일이 손상돼요.

제한 사항 (Limitations)

밑바탕이 되는 Azure Files 서비스는 파일을 늘리는( growing) 걸 허용하지 않아요. 파일 길이는 생성 시점에 알아야 해요. 그 결과:

CamelFileLength 헤더는 producer에서도 중요한 의미를 가져요.
append 모드는 지원되지 않아요.

타임아웃에 관하여 (About Timeouts)

connectTimeout 옵션으로 연결하거나 연결을 끊는 타임아웃을 밀리초 단위로 설정할 수 있어요.

timeout 옵션은 밀리초 단위의 데이터 타임아웃으로만 적용돼요.

메타데이터 작업의 타임아웃은 readLockCheckInterval, timeout, 20_000 밀리초 중 최솟값이에요.

지금으로선 파일 업로드에는 타임아웃이 없어요. 업로드 중에 밑바탕 라이브러리가 타임아웃 경고를 로그에 남길 수 있는데, 이는 복구 가능하고 업로드는 계속될 수 있어요.

로컬 작업 디렉터리 사용하기 (Using Local Work Directory)

Camel은 원격 파일 서버에서 소비하면서 파일을 로컬 작업 디렉터리에 바로 다운로드하는 걸 지원해요. 이러면 원격 파일 내용 전체를 메모리로 읽지 않고 FileOutputStream으로 로컬 파일에 바로 스트리밍할 수 있어요.

Camel은 원격 파일과 같은 이름의 로컬 파일에 저장하는데, 다운로드되는 동안에는 .inprogress 확장자를 붙여요. 그다음 파일 이름을 바꿔 .inprogress 접미어를 제거하고, 마지막으로 Exchange가 완료되면 로컬 파일을 삭제해요.

그래서 원격 파일 서버에서 파일을 다운로드해 로컬 파일로 저장하고 싶다면 다음처럼 file 엔드포인트로 라우트하면 돼요:

Java
XML
YAML

from("azure-files://...&localWorkDirectory=/tmp").to("file://inbox");

<route>
  <from uri="azure-files://...&amp;localWorkDirectory=/tmp"/>
  <to uri="file://inbox"/>
</route>

- route:
    from:
      uri: azure-files://...
      parameters:
        localWorkDirectory: /tmp
      steps:
        - to:
            uri: file://inbox

팁 (Tip) 위의 라우트는 파일 내용 전체를 메모리로 읽지 않기 때문에 엄청나게 효율적이에요. 원격 파일을 로컬 파일 스트림에 바로 다운로드하고, java.io.File 핸들이 Exchange 바디로 쓰여요. 파일 producer는 이 점을 활용해서 작업 파일 java.io.File 핸들로 바로 작업하고 java.io.File.rename으로 대상 파일 이름을 지정할 수 있어요. Camel은 그게 로컬 작업 파일인 걸 알기 때문에, 어차피 작업 파일은 삭제될 예정이니 파일 복사 대신 rename을 쓰는 최적화를 할 수 있죠.

커스텀 필터링 (Custom Filtering)

Camel은 플러그형 필터링 전략을 지원해요. 이 전략은 Java에 내장된 org.apache.camel.component.file.GenericFileFilter를 쓰는 거예요. 그러면 엔드포인트에 그런 필터를 설정해서 처리되기 전에 특정 파일을 걸러 낼 수 있어요.

이 샘플에서는 파일 이름이 report로 시작하는 파일만 받아들이는 필터를 직접 만들었어요.

그다음 spring XML 파일에 정의한 필터(# 표기법 사용)를 filter 속성으로 참조해서 라우트를 설정할 수 있어요:

accept(file)의 file 인자는 다음 프로퍼티를 가져요:

endpoint path: /samples 같은 share 이름
relative path: subdir/a file 같은 파일 경로
directory: 디렉터리라면 true
file length: 디렉터리가 아니라면 파일의 바이트 단위 길이

ANT 경로 매처로 필터링하기 (Filtering using ANT path matcher)

ANT 경로 매처는 camel-spring jar에 기본으로 들어 있는 필터예요. 그래서 Maven을 쓴다면 camel-spring에 의존해야 해요.
이유는 실제 매칭에 Spring의 AntPathMatcher를 활용하기 때문이에요.

파일 경로는 다음 규칙으로 매칭돼요:

?는 한 문자와 일치해요
*는 0개 이상의 문자와 일치해요
**는 경로 안의 0개 이상의 디렉터리와 일치해요

아래 샘플이 사용법을 보여 줘요:

Java
XML
YAML

from("azure-files://...&antInclude=**/*.txt").to("...");

<route>
  <from uri="azure-files://...&amp;antInclude=**/*.txt"/>
  <to uri="..."/>
</route>

- route:
    from:
      uri: azure-files://...
      parameters:
        antInclude: "**/*.txt"
      steps:
        - to:
            uri: "..."

프록시 사용하기 (Using a Proxy)

밑바탕 라이브러리 문서를 참고하세요.

고정 이름으로 단일 파일 소비하기 (Consuming a single file using a fixed name)

FTP 컴포넌트는 다음 옵션 조합으로 고정 이름의 단일 파일 사용 사례를 최적화해요:

useList=false
fileName=myFileName.txt
ignoreFileNotFoundOrPermissionError=true

이 컴포넌트는 그렇지 못해서 일반 필터로 대체해야 해요(즉, list 권한이 필요해요).

디버그 로깅 (Debug logging)

이 컴포넌트에는 TRACE 로그 레벨이 있어서 문제가 있을 때 도움이 될 수 있어요.

더 알아보기 (Learn more)

더 많은 샘플과 세부 동작은 FTP 컴포넌트 문서에서 확인할 수 있어요. 이 컴포넌트는 FTP 컴포넌트를 본떠 만든 것이라 개념이 대부분 그대로 통합니다. Azure Storage Files 서비스 자체에 대한 소개는 Microsoft Learn의 Azure Files 문서를 참고하고, 밑바탕 라이브러리 관련 설정(예: 프록시)은 Azure Java SDK 프록시 문서를 따르는 게 좋아요.

Azure Files

Azure Files (camel-azure-files)

본문

엔드포인트 URI 형식 (Endpoint URI Format)

옵션 설정 (Configuring Options)

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

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

컴포넌트 옵션 (Component Options)

엔드포인트 옵션 (Endpoint Options)

Path 파라미터 (Path Parameters)

Query 파라미터 (Query Parameters)

메시지 헤더 (Message Headers)

엔드포인트 URI 예시 (Endpoint URI Examples)

사용법 (Usage)

경로 (Paths)

동시성 (Concurrency)

더 알아보기 (More Information)

파일 소비하기 (Consuming Files)

바디 타입 옵션 (Body Type Options)

제한 사항 (Limitations)

Exchange 프로퍼티 (Exchange Properties)

파일 생산하기 (Producing Files)

제한 사항 (Limitations)

타임아웃에 관하여 (About Timeouts)

로컬 작업 디렉터리 사용하기 (Using Local Work Directory)

커스텀 필터링 (Custom Filtering)

ANT 경로 매처로 필터링하기 (Filtering using ANT path matcher)

프록시 사용하기 (Using a Proxy)

고정 이름으로 단일 파일 소비하기 (Consuming a single file using a fixed name)

디버그 로깅 (Debug logging)

더 알아보기 (Learn more)

함께 읽는 실무 이야기