タグ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 を 2 つの仮想ホストでクロールした場合は 2 つのドキュメントになります。仮想ホストを持たないタグと、仮想ホストを持たないドキュメントは、これまでどおりです（後述の「仮想ホスト」を参照）。

各タグには次の識別子があります。

value

タグの値です。 base64url(名前):base64url(所有者) （パディングなし、UTF-8）の形式で、インデックスの tag フィールドに格納されます。検索の絞り込みに使う不透明な値として扱ってください。

id

タグ ID です。 value の SHA-256 を小文字の 16 進数で表した 64 文字の文字列です。 /api/v2/tags/{tagId} などのパスに指定します。名前を変更すると value と id の両方が変わります。

タグ名は NFKC で正規化され、連続する空白は 1 つにまとめられ、前後の空白は取り除かれます。正規化後の長さは 1 〜 user.tag.name.max.length （デフォルト: 50 ）文字で、制御文字や書式文字（ゼロ幅文字や双方向の上書きなど）を含む名前は拒否されます。

仮想ホスト

仮想ホストを設定している場合、タグはタグのファセットと同じく、リクエストの仮想ホストに従います。

  • タグには、作成したリクエストの仮想ホストが記録されます。

  • 仮想ホストに一致したリクエストでは、 GET /api/v2/tags とドキュメントのタグ API の addable に、その仮想ホストの呼び出し元のタグだけが返ります。他の仮想ホストのタグや、仮想ホストを持たないタグは返りません。そのタグの名前の変更、削除、 id を指定したドキュメントへの追加は not_found (404) になり、 name を指定したドキュメントへの追加は conflict (409) になります。1 人のユーザーは、仮想ホストをまたいで同じ名前のタグを 1 つしか持てないためです。仮想ホストに一致しないリクエストには、すべてのタグが見えます。

  • 仮想ホストを持つタグは、そのドキュメントのクロール設定に同じ仮想ホストが設定されている場合にだけ、ドキュメントに付きます。ドキュメントを再度インデックスするとき、 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 で拒否されます。

1 人のユーザーに見えるタグは、自分のタグを優先して最大 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": "9667e32d74c547190e8f47b5e59ef88eb4c28ed40cf569126385db4545f6dfc5",
        "value": "6KaB56K66KqN:dGFybw",
        "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の概要 を参照）。

  • 1 人のユーザーが持てるタグは最大 user.tag.max.tags （デフォルト: 1000 ）個です。超える場合は invalid_request (400) になります。

  • 呼び出し元が同じ名前のタグをすでに持っている場合は conflict (409) になります。他のユーザーが同じ名前のタグを持っていても作成できます。

リクエストボディは Content-Type: application/json で、最大サイズは 1 KiB（1024 バイト）です。

{
  "name": "要確認",
  "shared": false
}
リクエストボディ
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) になります。

{
  "name": "確認済み",
  "shared": true
}

成功時（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": "9667e32d74c547190e8f47b5e59ef88eb4c28ed40cf569126385db4545f6dfc5",
        "value": "6KaB56K66KqN:dGFybw",
        "name": "要確認",
        "owner": "taro",
        "mine": true,
        "shared": false
      },
      {
        "id": "303c4b8db4750ec89c37582674e67027df02170efe1449637384f8f73a17d105",
        "value": "5LuV5qeY5pu4:aGFuYWtv",
        "name": "仕様書",
        "owner": "hanako",
        "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": "要確認"
}

  • name を指定し、呼び出し元がその名前のタグを持っていない場合は、非公開のタグを作成して付けます。作成したタグは user.tag.max.tags に数えられます。

  • 1 つのタグを付けられる 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 1 人のユーザーが持てるタグの最大数。 1000
user.tag.max.paths 1 つのタグを付けられる URL の最大数。 10000
user.tag.queue.max.size ドキュメントに反映されるまでメモリ上に保持する変更の最大数。超えた変更は破棄され、WARN ログが出力されます。 10000
user.tag.process.batch.size 変更をドキュメントに反映するときに、1 回のバルクリクエストで更新する URL の数。 100
user.tag.visible.max.size 検索で 1 人のユーザーに見えるタグの最大数。 1000