원시 파일 가져오기 필터
fileImportFilters는 실행 전에 원천 파일을 선택하는 FileImportFilter 목록입니다. 필터는 배열에 지정한 순서대로 적용하며 순서에 따라 실행 비용이 달라질 수 있습니다. 순서를 바꿀 때는 파일 수 제한과 최소 개수 조건의 적용 위치도 함께 검토합니다.
각 항목은 type으로 구분합니다. customFilter는 조회할 수 있지만 현재 생성 및 갱신 요청에는 사용할 수 없습니다. 조회한 사용자 지정 필터를 자동으로 삭제하여 대체 요청을 만드는 방식은 기존 선택 조건을 바꿀 수 있습니다.
분기 pathNotMatchesFilter
소스 루트를 기준으로 한 상대 경로가 정규식과 일치하지 않는 파일만 가져옵니다. 경로별 선택 예시는 아래 경로 필터 절에 있습니다.
| 이름 | 자료형 | 필수 여부 | 의미와 조건 | 예시 값 |
|---|---|---|---|---|
type | enum | 필수 | 분기를 구분하는 type 값입니다. 허용값: pathNotMatchesFilter. | pathNotMatchesFilter |
regex | string | 필수 | 하위 폴더를 지정했더라도 소스 루트를 기준으로 한 전체 상대 경로에 맞는 정규식을 사용합니다. | subfolder1/subfolder2/.* |
분기 anyPathMatchesFilter
정규식과 일치하는 상대 경로의 파일이 하나라도 있으면, 다른 필터로 제외되지 않은 하위 폴더의 파일을 모두 동기화합니다.
| 이름 | 자료형 | 필수 여부 | 의미와 조건 | 예시 값 |
|---|---|---|---|---|
type | enum | 필수 | 분기를 구분하는 type 값입니다. 허용값: anyPathMatchesFilter. | anyPathMatchesFilter |
regex | string | 필수 | 상대 경로에 적용할 정규식입니다. | subfolder1/subfolder2/.* |
분기 filesCountLimitFilter
각 트랜잭션에서 filesCount개까지만 가져옵니다. 어떤 파일을 먼저 선택할지는 보장하지 않습니다. 증분 동기화의 신뢰성을 높이는 데 사용할 수 있습니다.
| 이름 | 자료형 | 필수 여부 | 의미와 조건 | 예시 값 |
|---|---|---|---|---|
type | enum | 필수 | 분기를 구분하는 type 값입니다. 허용값: filesCountLimitFilter. | filesCountLimitFilter |
filesCount | integer | 필수 | 트랜잭션에서 가져올 파일 수이며 양수여야 합니다. | 5 |
분기 changedSinceLastUploadFilter
수집 이력에 없는 새 파일이나 마지막 수집 이후 지정한 속성이 바뀐 파일만 가져옵니다. 가져오기 모드와 관계없이 변경되지 않은 기존 파일을 제외하며, SNAPSHOT으로 바꾸어도 필터 이력이 초기화되지 않습니다.
| 이름 | 자료형 | 필수 여부 | 의미와 조건 | 예시 값 |
|---|---|---|---|---|
type | enum | 필수 | 분기를 구분하는 type 값입니다. 허용값: changedSinceLastUploadFilter. | changedSinceLastUploadFilter |
fileProperties | list<FileProperty> | 선택 | 변경 여부를 판단할 속성입니다. LAST_MODIFIED는 마지막 수정 시각, SIZE는 파일 크기를 비교합니다. 지정한 기준 중 하나라도 바뀌면 변경된 파일로 판단합니다. 기준을 지정하지 않으면 새로 추가된 파일만 가져옵니다. |
fileProperties의 구조
배열 항목은 FileProperty이며 자료형은 enum입니다.
허용값: LAST_MODIFIED, SIZE.
분기 customFilter
사용자 지정 파일 필터입니다. 조회는 가능하지만 현재 API의 생성이나 갱신 요청에는 사용할 수 없습니다.
| 이름 | 자료형 | 필수 여부 | 의미와 조건 | 예시 값 |
|---|---|---|---|---|
type | enum | 필수 | 분기를 구분하는 type 값입니다. 허용값: customFilter. | customFilter |
config | any | 필수 | 조회한 사용자 지정 필터의 구성입니다. |
분기 lastModifiedAfterFilter
지정한 시각보다 나중에 수정된 파일만 가져옵니다.
| 이름 | 자료형 | 필수 여부 | 의미와 조건 | 예시 값 |
|---|---|---|---|---|
type | enum | 필수 | 분기를 구분하는 type 값입니다. 허용값: lastModifiedAfterFilter. | lastModifiedAfterFilter |
afterTimestamp | string (date-time) | 선택 | ISO-8601 형식의 기준 시각입니다. 생략하면 이 필터를 파일 가져오기에 추가한 시각을 사용합니다. | 2020-01-01T00:00:00Z |
분기 pathMatchesFilter
소스 루트를 기준으로 한 상대 경로가 정규식과 일치하는 파일만 가져옵니다. 경로별 선택 예시는 아래 경로 필터 절에 있습니다.
| 이름 | 자료형 | 필수 여부 | 의미와 조건 | 예시 값 |
|---|---|---|---|---|
type | enum | 필수 | 분기를 구분하는 type 값입니다. 허용값: pathMatchesFilter. | pathMatchesFilter |
regex | string | 필수 | 하위 폴더를 지정했더라도 소스 루트를 기준으로 한 전체 상대 경로에 맞는 정규식을 사용합니다. | subfolder1/subfolder2/.* |
분기 atLeastCountFilter
필터 적용 후 남은 파일 수가 지정한 개수 이상일 때만 남은 파일을 모두 가져옵니다.
| 이름 | 자료형 | 필수 여부 | 의미와 조건 | 예시 값 |
|---|---|---|---|---|
type | enum | 필수 | 분기를 구분하는 type 값입니다. 허용값: atLeastCountFilter. | atLeastCountFilter |
minFilesCount | integer | 필수 | 필터 적용 후 남아 있어야 하는 최소 파일 수이며 0보다 커야 합니다. | 5 |
분기 fileSizeFilter
지정한 최소값과 최대값 사이의 크기를 가진 파일만 가져옵니다. gt 또는 lt 중 하나 이상이 필요합니다. 둘 다 지정하면 gt < lt - 1이어야 합니다.
| 이름 | 자료형 | 필수 여부 | 의미와 조건 | 예시 값 |
|---|---|---|---|---|
type | enum | 필수 | 분기를 구분하는 type 값입니다. 허용값: fileSizeFilter. | fileSizeFilter |
gt | long | 선택 | 파일 크기가 이 바이트 수보다 커야 합니다. 값은 음수일 수 없습니다. | 1023 |
lt | long | 선택 | 파일 크기가 이 바이트 수보다 작아야 합니다. 값은 1 이상이어야 합니다. | 1048577 |
경로 필터
가상의 소스에서 relative/subfolder를 수집하며 다음 세 파일이 있다고 가정합니다. 정규식에는 하위 폴더 안의 파일 이름만 넣지 않고 소스 루트 기준의 경로를 넣습니다.
| 파일 | pathMatchesFilter의 relative/subfolder/include-.*[.]txt | pathNotMatchesFilter의 relative/subfolder/exclude-.*[.]txt |
|---|---|---|
relative/subfolder/include-file.txt | 포함 | 포함 |
relative/subfolder/exclude-file.txt | 제외 | 제외 |
relative/subfolder/other-file.txt | 제외 | 포함 |
[.]은 확장자 앞의 점 문자입니다. 같은 세 파일에 다른 필터 없이 anyPathMatchesFilter를 적용하고 include 패턴을 사용하면, 일치하는 파일이 하나 있으므로 세 파일을 모두 선택합니다. 개별 파일을 고르는 pathMatchesFilter와 구분합니다.
파일 크기의 배타적 경계
gt와 lt는 모두 배타적 경계이며 단위는 바이트입니다. 다음은 1,024바이트부터 1,048,576바이트까지 선택하는 가상 조건입니다.
{"type":"fileSizeFilter","gt":1023,"lt":1048577}
둘 다 지정했다면 두 경계 사이에 유효한 정수 파일 크기가 있어야 하므로 gt < lt - 1을 만족해야 합니다. 예를 들어 gt: 1023, lt: 1024는 어떤 파일도 선택하지 못하는 잘못된 범위입니다.
변경 이력과 SNAPSHOT
changedSinceLastUploadFilter는 LAST_MODIFIED와 SIZE 중 하나라도 바뀐 경우를 변경으로 판단합니다. 비교 기준이 없으면 새 파일만 선택합니다. SNAPSHOT은 이 필터의 과거 수집 이력을 초기화하지 않습니다.
따라서 SNAPSHOT과 변경 이력 필터를 함께 쓰면 결과 데이터셋의 현재 상태에는 이번에 선택한 파일만 남습니다. 전체 파일을 다시 반영하려는 목적이라면 이 조합을 그대로 사용하지 않습니다. 기존 파일 변경을 반영하려면 파일 수집 모드의 조건을 함께 확인합니다.
lastModifiedAfterFilter.afterTimestamp를 생략하면 필터를 작업에 추가한 시각이 기준입니다. 매 실행의 시작 시각이나 마지막 성공 시각으로 임의 해석하지 않습니다.