FailureUrl API

개요

FailureUrl API는 Fess 의 크롤링 실패 URL을 관리하기 위한 API입니다. 크롤링 중 오류가 발생한 URL의 목록 조회, 개별 조회, 삭제 등을 조작할 수 있습니다.

기본 URL

/api/admin/failureurl

엔드포인트 목록

메서드 경로 설명
GET /logs 실패 URL 목록 조회
GET /log/{id} 실패 URL 조회
DELETE /log/{id} 실패 URL 삭제
DELETE /all 모든 실패 URL 삭제

실패 URL 목록 조회

요청

GET /api/admin/failureurl/logs

파라미터

파라미터 타입 필수 설명
size Integer 아니오 페이지당 건수 (기본값: 25. fess_config.properties 의 paging.page.size 로 변경 가능)
page Integer 아니오 페이지 번호 (1부터 시작, 기본값: 1)
url String 아니오 URL 필터 (와일드카드 * ? 지원)
error_count_min Integer 아니오 오류 횟수의 하한값 (지정한 값 이상)
error_count_max Integer 아니오 오류 횟수의 상한값 (지정한 값 이하)
error_name String 아니오 오류 이름 필터 (저장된 완전한정 클래스명에 대한 와일드카드 매칭; * ? 지원)

이 파라미터들은 JSON 요청 본문(예: {"size": 50, "page": 1} )으로 지정합니다. URL 쿼리 문자열(예: ?size=50 )로 지정한 값은 무시되므로, 본문에 지정하지 않으면 항상 처음 25건이 반환됩니다.

응답

{
  "response": {
    "status": 0,
    "logs": [
      {
        "id": "failure_id_1",
        "url": "https://example.com/broken-page",
        "thread_name": "Crawler-1",
        "error_name": "java.net.ConnectException",
        "error_log": "Connection refused: connect",
        "error_count": "3",
        "last_access_time": "1738144800000",
        "config_id": "webConfig_id_1"
      },
      {
        "id": "failure_id_2",
        "url": "https://example.com/not-found",
        "thread_name": "Crawler-2",
        "error_name": "org.codelibs.fess.exception.ContentNotFoundException",
        "error_log": "Not found: https://example.com/not-found",
        "error_count": "1",
        "last_access_time": "1738143000000",
        "config_id": "webConfig_id_1"
      }
    ],
    "total": 45
  }
}

응답 필드

필드 설명
id 실패 URL ID
url 실패한 URL
thread_name 스레드 이름
error_name 오류 이름 (발생한 예외의 완전한정 클래스명; 예: java.net.ConnectException)
error_log 오류 로그 (예외 메시지 또는 스택 트레이스)
error_count 오류 발생 횟수 (문자열로 표현된 숫자값)
last_access_time 최종 접근 시각 (문자열로 표현된 에포크 밀리초)
config_id 크롤링 설정 ID

참고

모든 응답 필드는 문자열(JSON string)로 반환됩니다. error_count 는 문자열로 표현된 숫자값이며, last_access_time 은 문자열로 표현된 에포크 밀리초입니다.

실패 URL 조회

요청

GET /api/admin/failureurl/log/{id}

응답

{
  "response": {
    "status": 0,
    "log": {
      "id": "failure_id_1",
      "url": "https://example.com/broken-page",
      "thread_name": "Crawler-1",
      "error_name": "java.net.ConnectException",
      "error_log": "Connection refused: connect",
      "error_count": "3",
      "last_access_time": "1738144800000",
      "config_id": "webConfig_id_1"
    }
  }
}

실패 URL 삭제

요청

DELETE /api/admin/failureurl/log/{id}

응답

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

모든 실패 URL 삭제

모든 실패 URL을 삭제합니다. 파라미터는 없습니다.

요청

DELETE /api/admin/failureurl/all

응답

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

오류 타입

error_name 에는 크롤링 중 발생한 예외의 완전한정 클래스명이 있는 그대로 저장됩니다. 고정된 열거형이 아니며, 발생한 예외에 따라 어떠한 클래스명도 나타날 수 있습니다. 다음은 대표적인 예시입니다.

오류 이름 (예시) 설명
java.net.ConnectException 연결 거부 (서버에 접속할 수 없음)
java.net.UnknownHostException 호스트명을 해석할 수 없음 (DNS 오류)
java.net.SocketTimeoutException 연결 또는 읽기 타임아웃
javax.net.ssl.SSLException SSL/TLS 핸드셰이크 또는 인증서 오류
java.io.IOException 입출력 오류
org.codelibs.fess.exception.ContentNotFoundException crawler.failure.url.status.codes 에 설정된 HTTP 상태 코드를 반환한 URL (기본값: 403, 404, 410)
org.codelibs.fess.crawler.exception.MaxLengthExceededException 콘텐츠가 최대 길이를 초과함

사용 예

실패 URL 목록 조회

curl -X GET "http://localhost:8080/api/admin/failureurl/logs" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"size": 100, "page": 1}'

오류 횟수로 필터링

# 3회 이상 오류가 발생한 URL만 조회
curl -X GET "http://localhost:8080/api/admin/failureurl/logs" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"error_count_min": 3}'

오류 이름으로 필터링

# error_name에는 완전한정 클래스명을 저장하므로 와일드카드를 사용하여 지정합니다
curl -X GET "http://localhost:8080/api/admin/failureurl/logs" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"error_name": "*ConnectException"}'

실패 URL 조회

curl -X GET "http://localhost:8080/api/admin/failureurl/log/failure_id_1" \
     -H "Authorization: Bearer YOUR_TOKEN"

실패 URL 삭제

curl -X DELETE "http://localhost:8080/api/admin/failureurl/log/failure_id_1" \
     -H "Authorization: Bearer YOUR_TOKEN"

모든 실패 URL 삭제

curl -X DELETE "http://localhost:8080/api/admin/failureurl/all" \
     -H "Authorization: Bearer YOUR_TOKEN"

오류 타입별 집계

# 오류 타입별 카운트
curl -X GET "http://localhost:8080/api/admin/failureurl/logs" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"size": 1000}' | \
     jq '[.response.logs[].error_name] | group_by(.) | map({error: .[0], count: length})'

참고 정보