자동완성 API

자동완성 단어 목록 취득

요청

HTTP 메서드	GET
엔드포인트	`/api/v2/suggest-words`

Fess 에 http://<Server Name>/api/v2/suggest-words?q=fes 와 같은 요청을 전송하면 입력한 접두사에 대한 자동완성 단어 목록을 JSON 형식으로 받을 수 있습니다.

자동완성 단어에는 다음 3가지 생성원이 있습니다.

문서 — 크롤링한 문서로부터 생성됩니다. 취득하려면 관리 화면의 시스템 > 일반에서 “문서로 추천”을 활성화해야 합니다.
검색어 (검색 로그) — 사용자의 검색 로그로부터 생성됩니다. 취득하려면 관리 화면의 시스템 > 일반에서 “검색어로 추천”을 활성화해야 합니다.
사용자 사전 — 관리자가 등록한 자동완성 단어입니다. 위 설정에 관계없이 항상 반환됩니다.

“문서로 추천”과 “검색어로 추천”이 비활성화된 경우에도 API는 오류가 되지 않으며, 해당 자동완성 단어가 결과에 포함되지 않을 뿐입니다. 또한, 자동완성 단어는 요청한 사용자의 역할에 따라 자동으로 필터링됩니다.

응답 공통 엔벨로프 및 오류 모델에 대해서는 API 개요 를 참조하십시오.

요청 파라미터

사용 가능한 요청 파라미터는 다음과 같습니다.

요청 파라미터
q	자동완성할 검색어 (접두사). 생략한 경우 접두사 필터링 없이 자동완성 단어를 반환합니다. (예) `q=fes`
num	자동완성될 단어 수 (0 이상의 정수). 기본값 `10` . 숫자 이외의 값을 지정한 경우 기본값이 사용됩니다. (예) `num=20`
fn	자동완성 대상을 좁히는 필드 이름. 반복 지정으로 배열로 처리됩니다. (예) `fn=content&fn=title`
lang	검색 언어 지정. 반복 지정으로 배열로 처리됩니다. (예) `lang=en`
label	필터링할 레이블 (태그) 이름. 반복 지정으로 배열로 처리됩니다. 지정한 값은 각 자동완성 단어의 `types` 에 대해 조회됩니다. (예) `label=java`

참고

v2 에서는 필드 이름 지정에 fn 파라미터를 사용합니다 (v1 의 fields 와는 다릅니다). 값을 쉼표로 나열하는 대신 fn 을 반복 지정하여 여러 값을 전달합니다.

응답

성공 시에는 다음과 같은 공통 엔벨로프 형식의 응답이 반환됩니다.

{
  "response": {
    "status": 0,
    "q": "fes",
    "page_size": 10,
    "record_count": 355,
    "query_time": 18,
    "suggest_words": [
      {
        "text": "fess",
        "types": [
          "label1"
        ]
      }
    ]
  }
}

response 의 각 요소에 대해서는 다음과 같습니다.

응답 정보
q	요청된 검색어 (문자열). `q` 를 생략한 경우 빈 문자열이 됩니다.
page_size	요청된 자동완성 단어 수 ( `num` 의 값, 정수).
record_count	자동완성 단어 해당 총 건수 (64비트 정수).
query_time	쿼리 처리 시간. 단위는 밀리초 (64비트 정수).
suggest_words	자동완성 단어 배열. 각 요소는 `text` 와 `types` 를 가집니다.
text	자동완성 단어 (문자열).
types	자동완성 단어에 연결된 태그 배열 (문자열 배열). 각 태그는 문서의 `label` 또는 `virtual_host` 필드 값, 혹은 검색 로그에서 추출된 필터 조건에서 유래합니다. 태그가 없는 경우 빈 배열이 됩니다.

참고

types 에는 자동완성 단어의 종별 ( document 또는 query 와 같은 종별 값) 이 아닌 태그 값이 포함됩니다. 이 배열은 v1 의 자동완성 항목의 labels 필드에 해당합니다. label 요청 파라미터는 이 types 값에 대해 필터링을 수행합니다.

사용 예

curl 명령으로 요청 예:

오류 응답

자동완성 API 가 실패한 경우 공통 오류 엔벨로프가 반환됩니다. 오류 모델의 자세한 내용은 API 개요 를 참조하십시오.

오류 응답
상태 코드	설명
405 Method Not Allowed	지원되지 않는 HTTP 메서드가 지정된 경우. `Allow` 헤더에 `GET` 이 표시됩니다.
500 Internal Server Error	서버 내부 오류가 발생한 경우.