태그 API

이 문서에서는 로그인한 사용자가 자신의 태그를 관리하고 문서에 붙이는 Fess 의 v2 태그 API 에 대해 설명합니다. 공통 응답 엔벨로프·오류 모델·CSRF 에 대해서는 API 개요 를 참조하십시오.

베이스 URL은 http://<Server Name>/api/v2/ 입니다 (로컬 환경 예: http://localhost:8080/api/v2 ).

참고

태그 기능은 기본적으로 비활성화되어 있습니다. 사용하려면 fess_config.properties 에서 user.tag.enabled=true 를 설정하십시오. /api/v2/ui/config 의 features.user_tag 로 상태를 확인할 수 있습니다. 비활성화되어 있는 동안에는 CSRF·Origin 검증을 통과하고 허용된 HTTP 메서드를 사용하는 요청에 대해 태그 API 가 invalid_request (400)를 반환합니다.

태그의 구조

태그는 사용자별로 관리됩니다. 태그를 만든 사용자가 그 태그의 소유자이며, 소유자는 로그인 사용자 ID 입니다. 같은 이름의 태그라도 소유자가 다르면 별개의 태그입니다.
태그는 로그인한 사용자만 사용할 수 있습니다. 모든 태그 API 는 세션의 로그인 사용자로서 동작하며, 액세스 토큰은 로그인을 대신하지 않습니다. 로그인하지 않은 호출자는 auth_required (401)가 됩니다.
새 태그는 비공개로, 소유자만 볼 수 있습니다. 소유자가 태그를 「공유」하면 로그인한 모든 사용자가 그 태그를 보고 필터링에 사용할 수 있습니다. 로그인하지 않은 사용자에게는 공유 태그도 보이지 않습니다.
태그를 변경·삭제하거나 문서에 붙이고 뗄 수 있는 것은 소유자뿐입니다. 다른 사용자의 공유 태그는 표시와 필터링에만 사용할 수 있습니다. 관리자는 관리 화면에서 모든 태그를 관리할 수 있습니다( 태그 참조).
태그는 문서의 URL 에 붙습니다. 같은 URL 을 가진 인덱스상의 모든 문서에 태그가 붙습니다. 다만 가상 호스트가 있는 태그는 그 가상 호스트가 있는 크롤 설정의 문서에만 붙습니다. 같은 URL 을 두 가상 호스트로 크롤하면 두 개의 문서가 됩니다. 가상 호스트가 없는 태그와 가상 호스트가 없는 문서는 이전과 같습니다(아래 “가상 호스트” 참조).

각 태그에는 다음 식별자가 있습니다.

value: 태그 값입니다. base64url(이름):base64url(소유자) (패딩 없음, UTF-8) 형식으로 인덱스의 tag 필드에 저장됩니다. 검색 결과를 좁히는 데 사용하는 불투명한 값으로 취급하십시오.
id: 태그 ID 입니다. value 의 SHA-256 을 소문자 16진수로 나타낸 64자의 문자열입니다. /api/v2/tags/{tagId} 등의 경로에 지정합니다. 이름을 변경하면 value 와 id 가 모두 바뀝니다.

태그 이름은 NFKC 로 정규화되고, 연속된 공백은 하나로 합쳐지며, 앞뒤 공백은 제거됩니다. 정규화 후의 길이는 1 ~ user.tag.name.max.length (기본값: 50 )자이며, 제어 문자나 서식 문자(폭 없는 문자나 양방향 재정의 등)를 포함한 이름은 거부됩니다.

가상 호스트

가상 호스트를 설정한 경우, 태그는 태그 패싯과 마찬가지로 요청의 가상 호스트를 따릅니다.

태그에는 태그를 만든 요청의 가상 호스트가 기록됩니다.
가상 호스트와 일치하는 요청에서는 GET /api/v2/tags 와 문서 태그 API의 addable 에 해당 가상 호스트의 호출자 태그만 반환됩니다. 다른 가상 호스트의 태그나 가상 호스트가 없는 태그는 반환되지 않습니다. 그 태그의 이름 변경, 삭제, id 를 지정한 문서 추가는 not_found (404)가 되고, name 을 지정한 문서 추가는 conflict (409)가 됩니다. 한 사용자는 가상 호스트에 관계없이 같은 이름의 태그를 하나만 가질 수 있기 때문입니다. 가상 호스트와 일치하지 않는 요청에는 모든 태그가 보입니다.
가상 호스트가 있는 태그는 문서의 크롤 설정에 같은 가상 호스트가 설정된 경우에만 문서에 붙습니다. 문서를 다시 색인할 때, tag_updater 작업을 실행할 때, 문서에 태그를 붙일 때 적용됩니다. 가상 호스트가 없는 태그와 가상 호스트가 없는 문서는 제한되지 않습니다.
관리자는 태그 유형 관리 화면에서 태그의 가상 호스트를 변경하거나 태그를 삭제할 수 있습니다( 태그 참조).

검색에서의 이용

user.tag.enabled 가 true 인 동안 검색 API( /api/v2/search )는 태그를 다음과 같이 다룹니다.

각 히트에 호출자에게 보이는 태그를 tags 로 반환합니다. 각 요소는 value , name , owner , mine (호출자가 소유자이면 true ), shared (공유 태그이면 true )입니다. 보이는 태그가 없으면 tags 는 반환되지 않습니다. 인덱스의 tag 필드 자체는 반환되지 않습니다.
facet.field=tag 를 지정하면 facet_field 에 호출자에게 보이는 태그만의 패싯이 반환됩니다. 각 버킷에는 value 와 count 외에 label (태그 이름), owner , mine , shared 가 붙습니다.
fields.tag=<value> 로 태그가 붙은 문서로 좁힐 수 있습니다. 값에는 히트의 tags 또는 패싯의 value 를 그대로 지정합니다.

태그를 지정하는 조건( fields.tag , tag: , ex_q , facet.query )은 호출자에게 보이는 태그 값과의 완전 일치만 유효합니다. 보이지 않는 태그의 값이나 와일드카드·접두사·퍼지·범위 조건은 아무것과도 일치하지 않습니다. 로그인하지 않은 호출자에게는 태그도 태그 패싯도 반환되지 않으며, 태그 조건은 아무것과도 일치하지 않습니다.

태그의 값에는 : 가 포함되므로 쿼리에서는 따옴표로 묶어야 합니다. q=tag:"<value>" 는 사용할 수 있지만, 따옴표가 없는 q=tag:<value> 는 아무것과도 일치하지 않고 ex_q=tag:<value> 는 HTTP 400 으로 거부됩니다.

한 사용자에게 보이는 태그는 자신의 태그를 우선하여 최대 user.tag.visible.max.size (기본값: 1000 )개입니다. 이를 넘는 태그는 히트의 tags 와 패싯에 나타나지 않습니다(필터링에는 사용할 수 있습니다).

문서에 대한 반영

태그의 생성·변경·삭제와 문서에 대한 붙이기·떼기는 태그 API 에 즉시 반영됩니다. 한편 인덱스 문서의 tag 필드는 변경을 메모리상의 큐에 넣고, 1분마다 실행되는 「Log Aggregator」( log_aggregator ) 작업이 일괄로 갱신합니다. 따라서 검색 결과의 히트나 패싯, 필터링에 반영되기까지 최대 1분 정도 걸립니다. 이름을 변경한 태그는 다음에 큐가 처리될 때까지 문서상의 이전 값이 보이지 않으므로 검색 결과에 표시되지 않습니다.

큐의 취급과 작업에 대해서는 태그 를 참조하십시오.

태그 목록 가져오기

요청

HTTP 메서드	GET
엔드포인트	`/api/v2/tags`

호출자가 소유한 태그를 표시 순서와 이름 순으로 반환합니다. 다른 사용자의 공유 태그는 포함되지 않습니다.

응답

성공 시(200)에는 공통 엔벨로프의 response 바로 아래에 다음 필드가 반환됩니다.

{
  "response": {
    "status": 0,
    "tags": [
      {
        "id": "a75185a5b3226fe910c69a7892e51a2ce3fb6beecaeaa7de18a277f045cc23a0",
        "value": "6rKA7YagIO2VhOyalA:bWluc3U",
        "name": "검토 필요",
        "shared": false,
        "sort_order": 0,
        "path_count": 3
      }
    ]
  }
}

응답 필드
`tags`	호출자의 태그 배열. 각 요소는 `id` , `value` , `name` , `shared` (공유 태그이면 `true` ), `sort_order` (표시 순서), `path_count` (태그를 붙인 URL 의 수).

표: 응답 필드

태그 생성

요청

HTTP 메서드	POST
엔드포인트	`/api/v2/tags`

호출자의 태그를 생성합니다. 상태를 변경하는 요청이므로 X-Fess-CSRF-Token 헤더가 필요합니다( API 개요 참조).

한 사용자가 가질 수 있는 태그는 최대 user.tag.max.tags (기본값: 1000 )개입니다. 초과하면 invalid_request (400)가 됩니다.
호출자가 같은 이름의 태그를 이미 가지고 있으면 conflict (409)가 됩니다. 다른 사용자가 같은 이름의 태그를 가지고 있어도 생성할 수 있습니다.

요청 본문은 Content-Type: application/json 이며, 최대 크기는 1 KiB(1024 바이트)입니다.

요청 본문
`name`	태그 이름(str, 필수).
`shared`	`true` 로 하면 로그인한 모든 사용자가 태그를 볼 수 있습니다(bool, 기본값: `false` ).

표: 요청 본문

응답

성공 시(200)에는 response 바로 아래의 tag 에 생성한 태그( GET /api/v2/tags 의 요소와 같은 형식, path_count 는 0 )가 반환됩니다.

태그 변경

요청

HTTP 메서드	PUT
엔드포인트	`/api/v2/tags/{tagId}`

호출자의 태그 이름 변경과 공유 전환을 수행합니다. X-Fess-CSRF-Token 헤더가 필요합니다.

요청 본문에는 name 과 shared 중 적어도 하나를 지정합니다.
name 으로 이름을 변경하면 태그의 id 와 value 가 새로워집니다. 이전 값을 가진 문서는 다음에 큐가 처리될 때 새 값으로 바뀝니다. 호출자가 이미 사용 중인 이름으로 변경하려 하면 conflict (409)가 되며 태그는 변경되지 않습니다.
shared 는 태그를 볼 수 있는 사용자만 바꿉니다. 문서 갱신은 필요하지 않습니다. shared 를 false 로 해도 관리자가 권한에 추가한 역할이나 그룹은 그대로 남습니다.
다른 사용자의 공유 태그는 forbidden (403), 호출자에게 보이지 않는 태그는 not_found (404)가 됩니다.
다른 갱신과 경합하여 쓰기에 반복해서 실패한 경우에도 conflict (409)가 됩니다.

성공 시(200)에는 response 바로 아래에 tag (변경 후의 태그)와 renamed (이름을 변경한 경우 true . 이때 tag.id 와 tag.value 는 새 값)가 반환됩니다.

태그 삭제

요청

HTTP 메서드	DELETE
엔드포인트	`/api/v2/tags/{tagId}`

호출자의 태그를 삭제합니다. 문서에서는 다음에 큐가 처리될 때 태그 값이 제거됩니다. X-Fess-CSRF-Token 헤더가 필요합니다. 다른 사용자의 공유 태그는 forbidden (403), 호출자에게 보이지 않는 태그는 not_found (404)가 됩니다.

성공 시(200)에는 response 바로 아래에 id (삭제한 태그 ID)와 deleted (항상 true )가 반환됩니다.

문서의 태그 가져오기

요청

HTTP 메서드	GET
엔드포인트	`/api/v2/documents/{docId}/tags`

문서의 URL 에 붙은 태그 중 호출자에게 보이는 것과, 아직 붙지 않은 호출자의 태그를 반환합니다. 문서는 호출자의 역할로 검색되므로 호출자가 검색할 수 없는 문서는 not_found (404)가 됩니다.

응답

성공 시(200)에는 공통 엔벨로프의 response 바로 아래에 다음 필드가 반환됩니다.

{
  "response": {
    "status": 0,
    "doc_id": "a1b2c3d4e5f6",
    "tags": [
      {
        "id": "a75185a5b3226fe910c69a7892e51a2ce3fb6beecaeaa7de18a277f045cc23a0",
        "value": "6rKA7YagIO2VhOyalA:bWluc3U",
        "name": "검토 필요",
        "owner": "minsu",
        "mine": true,
        "shared": false
      },
      {
        "id": "41e429a7d0081e25390c3840268d736dca00250167bab94250389aee9e08e2ed",
        "value": "c3BlY3M:Ym9i",
        "name": "specs",
        "owner": "bob",
        "mine": false,
        "shared": true
      }
    ],
    "addable": []
  }
}

응답 필드
`doc_id`	문서 ID(str).
`tags`	문서의 URL 에 붙은 태그 중 호출자에게 보이는 것의 배열. 각 요소는 `id` , `value` , `name` , `owner` (소유자), `mine` (호출자가 소유자이면 `true` ), `shared` (공유 태그이면 `true` ).
`addable`	문서의 URL 에 아직 붙지 않은 호출자의 태그 배열(요소의 형식은 `tags` 와 같음).
`added`	POST 만. 태그가 이미 붙어 있던 경우 `false` (bool).
`tag`	POST 만. 문서에 붙인 태그(요소의 형식은 `tags` 와 같음).
`removed`	DELETE 만. 태그가 붙어 있지 않았던 경우 `false` (bool).

표: 응답 필드

문서에 태그 추가

요청

HTTP 메서드	POST
엔드포인트	`/api/v2/documents/{docId}/tags`

문서의 URL 을 호출자의 태그에 추가합니다. X-Fess-CSRF-Token 헤더가 필요합니다.

요청 본문( Content-Type: application/json , 최대 1 KiB)에서는 id 로 기존 태그를 지정하거나 name 으로 태그 이름을 지정합니다. 둘 다 지정한 경우 id 가 우선합니다.

name 을 지정했는데 호출자가 그 이름의 태그를 가지고 있지 않으면, 비공개 태그를 생성하여 붙입니다. 생성한 태그는 user.tag.max.tags 에 포함됩니다.
하나의 태그를 붙일 수 있는 URL 은 최대 user.tag.max.paths (기본값: 10000 )개입니다. 초과하면 invalid_request (400)가 됩니다.
다른 사용자의 태그를 id 로 지정하면, 그 태그가 보이는 경우 forbidden (403), 보이지 않는 경우 not_found (404)가 됩니다.
성공 시에는 문서의 태그 가져오기와 같은 필드에 added 와 tag 를 더해 반환합니다. 태그는 API 상에서는 즉시 붙지만, 그 URL 의 문서 검색 결과에 반영되는 것은 다음에 큐가 처리될 때(1분 정도 후)입니다.

문서에서 태그 제거

요청

HTTP 메서드	DELETE
엔드포인트	`/api/v2/documents/{docId}/tags/{tagId}`

문서의 URL 을 tagId 로 지정한 호출자의 태그에서 제거합니다. X-Fess-CSRF-Token 헤더가 필요합니다. 다른 사용자의 태그는 보이는 경우 forbidden (403), 보이지 않는 경우 not_found (404)가 됩니다. 성공 시에는 문서의 태그 가져오기와 같은 필드에 removed 를 더해 반환합니다.

오류 응답

오류 모델의 자세한 내용은 API 개요 를 참조하십시오. 태그 API 가 반환하는 HTTP 상태는 다음과 같습니다.

오류 응답
상태 코드	설명
400 Bad Request	요청이 올바르지 않은 경우. 태그 기능이 비활성화된 경우, 태그 이름이 올바르지 않은 경우, 필수 항목이 없는 경우, `user.tag.max.tags` 나 `user.tag.max.paths` 의 상한을 넘는 경우를 포함합니다.
401 Unauthorized	로그인하지 않은 경우(액세스 토큰은 로그인을 대신하지 않습니다).
403 Forbidden	CSRF 토큰이 없거나 만료된 경우, 또는 다른 사용자의 태그를 변경하려 한 경우. CSRF 검증은 로그인 확인보다 먼저 이루어지므로, 세션이 없는 상태 변경 요청은 401 이 아니라 403 이 됩니다.
404 Not Found	태그가 존재하지 않거나 호출자에게 보이지 않는 경우, 또는 문서를 찾을 수 없거나 호출자가 검색할 수 없는 경우.
405 Method Not Allowed	HTTP 메서드가 허용되지 않는 경우.
409 Conflict	같은 이름의 태그가 이미 있는 경우, 또는 다른 갱신과 경합하여 쓸 수 없었던 경우.
413 Payload Too Large	요청 본문이 크기 상한(1 KiB)을 넘은 경우.
415 Unsupported Media Type	지원되지 않는 `Content-Type` 인 경우.
500 Internal Server Error	서버 내부 오류가 발생한 경우.

표: 오류 응답

설정

fess_config.properties 의 다음 설정으로 태그 기능을 조정할 수 있습니다.

속성	설명	기본값
`user.tag.enabled`	로그인한 사용자가 태그를 사용할 수 있는지 여부.	`false`
`user.tag.name.max.length`	태그 이름의 최대 길이(코드 포인트 수).	`50`
`user.tag.max.tags`	한 사용자가 가질 수 있는 태그의 최대 수.	`1000`
`user.tag.max.paths`	하나의 태그를 붙일 수 있는 URL 의 최대 수.	`10000`
`user.tag.queue.max.size`	문서에 반영될 때까지 메모리에 보관하는 변경의 최대 수. 초과한 변경은 버려지고 WARN 로그가 출력됩니다.	`10000`
`user.tag.process.batch.size`	변경을 문서에 반영할 때 한 번의 벌크 요청으로 갱신하는 URL 의 수.	`100`
`user.tag.visible.max.size`	검색에서 한 사용자에게 보이는 태그의 최대 수.	`1000`