BoostDoc API

개요

BoostDoc API는 Fess 의 문서 부스트 설정을 관리하기 위한 API입니다. 문서 부스트를 설정하면, 특정 조건에 일치하는 문서의 점수를 높여 검색 결과 상위에 표시되기 쉽게 할 수 있습니다.

부스트는 인덱스 생성 시(크롤링 시)에 각 문서에 적용됩니다. 조건(url_expr)과 부스트 값(boost_expr)은 script_type 필드에서 지정한 스크립트 엔진의 식으로 평가됩니다. script_type 에는 javascript 와 groovy``(``fess-script-groovy 플러그인 필요) 중 하나를 지정할 수 있습니다. 관리 화면의 신규 작성 화면에서는 script_type 에 javascript 가 미리 입력되지만, 이 API의 요청 본문에서 script_type 을 생략하면 자동으로 채워지지 않고 Groovy로 평가됩니다. 여러 규칙은 sort_order 의 오름차순으로 평가되며, 처음 조건이 일치한 규칙의 부스트 값만 적용됩니다 (일치하는 규칙이 발견되면, 이후 규칙은 평가되지 않습니다).

참고

관리 화면에서는 url_expr 은 “조건”, boost_expr 은 “부스트 값 식”, script_type 은 “스크립트 종류”로 표시됩니다. script_type 은 생성·수정·조회(목록·상세)의 요청 본문 및 응답에만 포함되며, 목록 조회의 필터 파라미터(url_expr, boost_expr)에는 포함되지 않습니다. 설정 항목의 자세한 내용은 문서 부스트 를 참조하십시오.

기본 URL

/api/admin/boostdoc

인증

이 API를 사용하려면 Radmin-api 권한을 가진 액세스 토큰이 필요합니다. 액세스 토큰 취득 방법과 지정 방법은 Admin API 개요 를 참조하십시오.

엔드포인트 목록

메서드 경로 설명
GET /settings 문서 부스트 목록 조회
GET /setting/{id} 문서 부스트 조회
POST /setting 문서 부스트 만들기
PUT /setting 문서 부스트 업데이트
DELETE /setting/{id} 문서 부스트 삭제

문서 부스트 목록 조회

요청

GET /api/admin/boostdoc/settings

파라미터

파라미터 타입 필수 설명
size Integer 아니오 페이지당 건수 (기본값: 25)
page Integer 아니오 페이지 번호 (1부터 시작. 기본값: 1)
url_expr String 아니오 조건식으로 필터링 (부분 일치)
boost_expr String 아니오 부스트 값 식으로 필터링 (부분 일치)

응답

{
  "response": {
    "status": 0,
    "settings": [
      {
        "id": "boostdoc_id_1",
        "url_expr": "url.startsWith(\"https://docs.example.com/\")",
        "boost_expr": "3.0",
        "script_type": "javascript",
        "sort_order": 1,
        "version_no": 1
      }
    ],
    "total": 5
  }
}

참고

위에 표시된 필드 외에도, 응답의 각 설정 객체에는 생성/업데이트 메타데이터(created_by, created_time, updated_by, updated_time)가 포함됩니다. version_no 는 업데이트(PUT) 시에 필수이므로, 업데이트 전에 조회 또는 목록 API를 통해 현재 값을 취득하십시오.

문서 부스트 조회

요청

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

응답

{
  "response": {
    "status": 0,
    "setting": {
      "id": "boostdoc_id_1",
      "url_expr": "url.startsWith(\"https://docs.example.com/\")",
      "boost_expr": "3.0",
      "script_type": "javascript",
      "sort_order": 1,
      "version_no": 1
    }
  }
}

문서 부스트 만들기

요청

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

요청 본문

{
  "url_expr": "url.startsWith(\"https://important.example.com/\")",
  "boost_expr": "5.0",
  "script_type": "javascript",
  "sort_order": 0
}

필드 설명

필드 필수 설명
url_expr 예 조건식. 부스트 대상 문서를 판별하는 스크립트 식으로, Boolean 을 반환합니다. 관리 화면의 “조건”에 해당합니다 (최대 10000자).
boost_expr 예 부스트 값 식. 부스트 값(숫자)을 반환하는 스크립트 식입니다. 3.0 과 같은 고정값도 지정할 수 있습니다. 관리 화면의 “부스트 값 식”에 해당합니다 (최대 10000자).
script_type 아니오 url_expr 과 boost_expr 을 평가하는 스크립트 엔진. javascript 또는 groovy``(``fess-script-groovy 플러그인 필요)를 지정합니다. 관리 화면의 “스크립트 종류”에 해당합니다 (최대 100자). 생략하면 Groovy로 평가됩니다.
sort_order 예 적용 순서. 규칙은 오름차순으로 평가되며, 처음 조건이 일치한 규칙의 부스트 값이 적용됩니다 (폼 초기값: 0, 0 이상의 정수).

응답

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

문서 부스트 업데이트

요청

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

요청 본문

{
  "id": "existing_boostdoc_id",
  "url_expr": "url.startsWith(\"https://important.example.com/\")",
  "boost_expr": "10.0",
  "script_type": "javascript",
  "sort_order": 0,
  "version_no": 1
}

업데이트 시에는 만들기 시의 필드에 더하여 id (대상 규칙의 ID, 최대 1000자)와 version_no (낙관적 잠금을 위한 버전 번호)가 필수입니다. version_no 에는 조회 또는 목록 API 응답에서 취득한 현재 버전 번호를 지정하십시오. 버전 번호가 일치하지 않으면 업데이트는 실패합니다.

응답

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

문서 부스트 삭제

요청

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

응답

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

조건식 및 부스트 값 식에 대하여

url_expr (조건)과 boost_expr (부스트 값 식)은 script_type``(기본값: Groovy. 관리 화면의 신규 작성 화면에서만 ``javascript 가 미리 입력됨)에서 지정한 스크립트 엔진의 식으로 평가됩니다. 식 안에서는 인덱스 대상 문서의 필드 값을 필드명 변수로 참조할 수 있습니다.

  • url_expr 은 Boolean 을 반환해야 합니다 (예: url.startsWith("https://docs.example.com/")). 단순 정규식 문자열 (예: .*docs\.example\.com.*)은 스크립트 식으로서 Boolean 을 반환하지 않으므로 조건으로 동작하지 않습니다. 정규식을 사용하는 경우에는 String#matches 를 이용합니다(Groovy와 JavaScript 모두 동일한 표기법으로 사용할 수 있습니다).

  • boost_expr 은 숫자를 반환해야 합니다. 결과는 float 으로 변환되며, 0보다 큰 경우에만 부스트가 적용됩니다.

참고

식 안에서 참조할 수 있는 주요 필드 변수: url, title, content, content_length, last_modified 등. click_count 와 favorite_count 는 각각 indexer.click.count.enabled / indexer.favorite.count.enabled (모두 기본적으로 활성화)가 설정된 경우에 참조할 수 있습니다. now - 7d 와 같은 OpenSearch 날짜 계산 구문은 Groovy와 JavaScript 모두에서 사용할 수 없습니다.

조건식(url_expr) 예시

조건식 설명
url.startsWith("https://docs.example.com/") 지정한 URL로 시작하는 문서를 대상으로 함
url.matches("https://www\\.example\\.com/.*") 정규식(String#matches)으로 URL을 판별함
title.contains("릴리스 노트") 제목에 특정 단어를 포함하는 문서를 대상으로 함

부스트 값 식(boost_expr) 예시

부스트 값 식 설명
3.0 고정값으로 부스트
click_count * 0.1 + 1 클릭 수에 따라 부스트
Math.log(click_count + 1) 클릭 수에 기반한 로그 스케일 부스트

사용 예

문서 사이트 부스트

curl -X POST "http://localhost:8080/api/admin/boostdoc/setting" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "url_expr": "url.startsWith(\"https://docs.example.com/\")",
       "boost_expr": "5.0",
       "sort_order": 0
     }'

클릭 수가 많은 콘텐츠 부스트

curl -X POST "http://localhost:8080/api/admin/boostdoc/setting" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "url_expr": "url.startsWith(\"https://www.example.com/\")",
       "boost_expr": "click_count * 0.1 + 1",
       "sort_order": 10
     }'

참고 정보