FileConfig API

개요

FileConfig API는 Fess 의 파일 크롤링 설정을 관리하기 위한 API입니다. 로컬 파일 시스템, SMB/CIFS 공유 폴더, FTP, 각종 오브젝트 스토리지 등의 크롤링 설정을 조작할 수 있습니다.

기본 URL

/api/admin/fileconfig

참고

모든 엔드포인트에는 관리자 권한과 유효한 액세스 토큰이 필요합니다. 인증 방법에 대해서는 Admin API 개요 를 참조하십시오.

엔드포인트 목록

메서드	경로	설명
GET	/settings	파일 크롤링 설정 목록 조회
GET	/setting/{id}	파일 크롤링 설정 조회
POST	/setting	파일 크롤링 설정 생성
PUT	/setting	파일 크롤링 설정 업데이트
DELETE	/setting/{id}	파일 크롤링 설정 삭제

파일 크롤링 설정 목록 조회

요청

GET /api/admin/fileconfig/settings

참고

목록 조회 엔드포인트는 GET 외에 PUT 으로도 접근할 수 있습니다.

파라미터

파라미터	타입	필수	설명
page	Integer	아니오	페이지 번호 (1부터 시작, 기본값: 1)
size	Integer	아니오	페이지당 건수 (기본값: 25. paging.page.size 설정에 따릅니다)
name	String	아니오	설정 이름으로 필터링
paths	String	아니오	크롤링 경로로 필터링
description	String	아니오	설명으로 필터링

응답

{
  "response": {
    "status": 0,
    "settings": [
      {
        "id": "fileconfig_id_1",
        "name": "Shared Documents",
        "description": "공유 문서",
        "paths": "smb://server/share/documents",
        "included_paths": ".*\\.pdf$",
        "excluded_paths": ".*/(temp|cache)/.*",
        "included_doc_paths": "",
        "excluded_doc_paths": "",
        "config_parameter": "",
        "depth": 10,
        "max_access_count": 1000,
        "num_of_thread": 1,
        "interval_time": 1000,
        "boost": 1.0,
        "available": "true",
        "permissions": "{role}admin",
        "virtual_hosts": "",
        "sort_order": 0
      }
    ],
    "total": 5
  }
}

total 은 조건에 일치하는 설정의 총 건수를 나타냅니다.

파일 크롤링 설정 조회

요청

GET /api/admin/fileconfig/setting/{id}

응답

{
  "response": {
    "status": 0,
    "setting": {
      "id": "fileconfig_id_1",
      "name": "Shared Documents",
      "description": "공유 문서",
      "paths": "smb://server/share/documents",
      "included_paths": ".*\\.pdf$",
      "excluded_paths": ".*/(temp|cache)/.*",
      "included_doc_paths": "",
      "excluded_doc_paths": "",
      "config_parameter": "",
      "depth": 10,
      "max_access_count": 1000,
      "num_of_thread": 1,
      "interval_time": 1000,
      "boost": 1.0,
      "available": "true",
      "sort_order": 0,
      "permissions": "{role}admin",
      "virtual_hosts": "",
      "created_by": "admin",
      "created_time": 1700000000000,
      "updated_by": "admin",
      "updated_time": 1700000000000,
      "version_no": 1
    }
  }
}

참고

응답에는 등록 및 업데이트 시 자동으로 설정되는 created_by, created_time, updated_by, updated_time, version_no 가 포함됩니다. version_no 는 업데이트 시 필요합니다 (아래의 「파일 크롤링 설정 업데이트」를 참조).

파일 크롤링 설정 생성

요청

POST /api/admin/fileconfig/setting
Content-Type: application/json

요청 본문

{
  "name": "Local Files",
  "paths": "file:///data/documents",
  "included_paths": ".*\\.(pdf|doc|docx|xls|xlsx)$",
  "excluded_paths": ".*/(temp|backup)/.*",
  "num_of_thread": 2,
  "interval_time": 500,
  "boost": 1.0,
  "available": "true",
  "sort_order": 0,
  "permissions": "{role}admin\n{role}user"
}

필드 설명

필드	필수	설명
name	예	설정 이름 (최대 200자)
description	아니오	설정 설명 (최대 1000자)
paths	예	크롤링 시작 경로 (여러 개인 경우 줄바꿈으로 구분). file:, smb:, smb1:, ftp:, s3:, gcs: 중 하나의 프로토콜로 지정합니다
included_paths	아니오	크롤링 대상 경로의 정규 표현식 패턴
excluded_paths	아니오	크롤링 제외 경로의 정규 표현식 패턴
included_doc_paths	아니오	인덱스 대상 경로의 정규 표현식 패턴
excluded_doc_paths	아니오	인덱스 제외 경로의 정규 표현식 패턴
config_parameter	아니오	추가 설정 파라미터 (key=value 형식, 한 줄에 한 항목)
depth	아니오	크롤링 깊이 (0 이상)
max_access_count	아니오	최대 접근 수 (0 이상)
num_of_thread	예	병렬 스레드 수 (1 이상)
interval_time	예	접근 간격 (밀리초, 0 이상)
boost	예	검색 결과 부스트 값
available	예	활성화/비활성화 (문자열 "true" / "false")
sort_order	예	표시 순서 (0 이상)
permissions	아니오	접근 허용 역할 (여러 개인 경우 줄바꿈으로 구분)
virtual_hosts	아니오	가상 호스트 (여러 개인 경우 줄바꿈으로 구분)

참고

created_by, created_time, updated_by, updated_time 등의 감사용 필드는 서버 측에서 자동으로 설정되므로 요청 본문에 지정할 필요가 없습니다.

응답

{
  "response": {
    "status": 0,
    "id": "new_fileconfig_id",
    "created": true
  }
}

파일 크롤링 설정 업데이트

요청

PUT /api/admin/fileconfig/setting
Content-Type: application/json

요청 본문

업데이트 시에는 생성 시의 필드에 더하여, 업데이트 대상을 식별하는 id 와 버전 번호 version_no 가 필수입니다. version_no 에는 조회 API (GET)의 응답에 포함된 현재 값을 지정합니다.

{
  "id": "existing_fileconfig_id",
  "name": "Updated Local Files",
  "paths": "file:///data/documents",
  "included_paths": ".*\\.(pdf|doc|docx|xls|xlsx|ppt|pptx)$",
  "excluded_paths": ".*/(temp|backup|archive)/.*",
  "depth": 10,
  "max_access_count": 10000,
  "num_of_thread": 3,
  "interval_time": 300,
  "boost": 1.2,
  "available": "true",
  "sort_order": 0,
  "version_no": 1
}

업데이트 시 추가 필드

필드	필수	설명
id	예	업데이트 대상의 설정 ID (최대 1000자)
version_no	예	업데이트 대상의 현재 버전 번호. 조회 API (GET)의 응답에 포함된 version_no 를 지정합니다

응답

{
  "response": {
    "status": 0,
    "id": "existing_fileconfig_id",
    "created": false
  }
}

파일 크롤링 설정 삭제

요청

DELETE /api/admin/fileconfig/setting/{id}

응답

{
  "response": {
    "status": 0
  }
}

경로 형식

paths 에는 다음 프로토콜을 사용할 수 있습니다 (지원 프로토콜은 crawler.file.protocols 설정으로 변경할 수 있습니다).

프로토콜	경로 형식
로컬 파일	file:///path/to/directory
SMB/CIFS 공유	smb://server/share/path
SMB/CIFS 공유 (SMB1)	smb1://server/share/path
FTP	ftp://server/path
Amazon S3 / S3 호환 오브젝트 스토리지 (MinIO 등)	s3://bucket/path
Google Cloud Storage	gcs://bucket/path

참고

SMB/CIFS 및 FTP의 인증 정보 (사용자 이름, 비밀번호)는 경로에 포함하지 않고 「파일 인증」 설정에서 구성합니다. 자세한 내용은 파일 인증 를 참조하십시오.

사용 예

로컬 파일 크롤링 설정

curl -X POST "http://localhost:8080/api/admin/fileconfig/setting" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Local Files",
       "paths": "file:///data/documents",
       "included_paths": ".*\\.(pdf|doc|docx)$",
       "excluded_paths": ".*/(temp|backup)/.*",
       "num_of_thread": 2,
       "interval_time": 500,
       "boost": 1.0,
       "available": "true",
       "sort_order": 0,
       "permissions": "{role}guest"
     }'

SMB 공유 크롤링 설정

curl -X POST "http://localhost:8080/api/admin/fileconfig/setting" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "SMB Share",
       "paths": "smb://server/documents",
       "included_paths": ".*\\.(pdf|doc|docx)$",
       "excluded_paths": ".*/(temp|private)/.*",
       "max_access_count": 50000,
       "num_of_thread": 3,
       "interval_time": 200,
       "boost": 1.0,
       "available": "true",
       "sort_order": 0,
       "permissions": "{role}guest"
     }'

참고

SMB 공유 접근에 인증이 필요한 경우, 사전에 「파일 인증」 설정에서 대상 호스트의 인증 정보를 등록해 주십시오.

참고 정보

• Admin API 개요 - Admin API 개요

• WebConfig API - 웹 크롤링 설정 API

• DataConfig API - 데이터스토어 설정 API

• 파일 크롤링(파일 서버 검색) - 파일 크롤링 설정 가이드

• 파일 인증 - 파일 인증 설정 가이드